Ollama 로컬 API 연결 확인: localhost 11434·모델 목록·인증 구분

Ollama를 연결할 때는 모델 다운로드보다 로컬 API 주소와 응답부터 확인하는 편이 문제 범위를 좁히기 쉽습니다. 이 글은 이미 설치된 환경에서 연결 상태를 읽는 방법만 다룹니다.

3줄 결론
로컬 기본 API는 http://localhost:11434/api이며, 기본 바인딩은 127.0.0.1의 11434 포트입니다.
GET /api/tags로 모델 목록을, GET /api/version으로 응답한 서버의 버전을 확인합니다.
로컬 API 자체는 인증이 필요 없지만, 직접 클라우드 호출과 로컬 경유 클라우드 모델은 인증 방식을 따로 구분해야 합니다.

공식 문서 확인일은 2026-10-14입니다. 특정 최신 릴리스 번호를 기준으로 설명하지 않습니다. 아래 명령은 문서에 근거한 사용 예시이며, 이 글을 작성하면서 사용자 PC에서 실행하거나 연결 성공을 테스트한 결과가 아닙니다.

주소와 인증을 먼저 구분하기

사용 방식	주소 또는 경로	인증 구분
로컬 Ollama API	http://localhost:11434/api	로컬 API 자체는 인증 불필요
Ollama 클라우드 직접 호출	https://ollama.com/api	API 키 필요
로컬 서버를 통한 클라우드 모델	로컬 API에서 클라우드 모델 지정	Ollama 로그인 필요

공식 소개의 localhost는 클라이언트가 요청하는 주소 표기이고, FAQ의 127.0.0.1은 서버가 기본으로 바인딩하는 주소입니다. 따라서 localhost라는 표기만 보고 다른 PC에서도 접속할 수 있다고 해석하면 안 됩니다. 두 문서가 설명하는 역할을 나눠 보면 주소와 접속 범위를 혼동하지 않을 수 있습니다.

1단계: 모델 목록을 GET으로 읽기

이미 실행 중인 로컬 서버가 있다는 전제로 아래 요청을 사용합니다. 모델 생성·다운로드·삭제를 요청하지 않고 목록을 조회하는 공식 GET 엔드포인트입니다. Windows PowerShell에서는 curl.exe를, macOS·Linux 셸에서는 curl을 사용하는 예시로 구분했습니다. PowerShell용 표기는 같은 HTTP GET 요청을 보내도록 정리한 예시이지, 공식 문서가 모든 Windows 환경을 보증한다는 의미는 아닙니다.

Windows PowerShell 예시

curl.exe --request GET http://localhost:11434/api/tags

macOS·Linux 셸 예시

curl --request GET http://localhost:11434/api/tags

공식 응답 형식은 models 배열이며, 항목에 name, model, modified_at, size, digest, details 등이 표시됩니다. 우선 모델 이름을 읽고 연결하려는 앱의 모델 지정값과 비교하세요. 예시 문서에 나온 모델이 내 PC에도 설치되어 있다는 뜻은 아닙니다. 목록 조회 성공은 그 요청이 서버에 도달했다는 확인이지, 특정 모델의 답변 생성이나 GPU 동작까지 검증한 결과는 아닙니다.

2단계: 응답한 서버의 버전 읽기

버전 조회는 모델 이름 없이 요청할 수 있는 별도의 GET 경로입니다. 모델 목록과 함께 기록하면 이후 공식 변경 내역을 대조할 때 기준을 잡기 좋습니다.

Windows PowerShell 예시

curl.exe --request GET http://localhost:11434/api/version

macOS·Linux 셸 예시

curl --request GET http://localhost:11434/api/version

응답의 version 문자열이 해당 서버에서 확인한 버전입니다. 문서의 샘플 숫자를 내 설치 버전이나 최신 버전으로 옮겨 적지 마세요. 명령이 응답하지 않았다면 버전 확인은 아직 끝나지 않은 상태입니다. 이 안내에는 서버 시작, 서비스 재시작, 모델 실행 명령을 포함하지 않습니다.

주의: 연결 오류 때문에 바인딩부터 넓히지 않기

FAQ는 OLLAMA_HOST 환경 변수로 바인딩 주소를 바꿀 수 있다고 설명하고, 운영체제별 설정 절차를 별도로 제공합니다. 이것은 인증을 켜는 설정이 아닙니다. 로컬 API가 인증 없이 동작한다는 공식 설명과 함께 고려하면, 네트워크 접근 범위를 넓힐 때 허가하지 않은 요청이 들어올 위험도 따져야 합니다. 방화벽·프록시 등 실제 접근 통제를 확인하지 않은 채 외부 노출을 연결 문제의 해결책으로 쓰지 마세요.

특히 localhost 주소를 사용했다는 이유만으로 요청한 모델이 항상 로컬에서 추론한다고 단정하면 안 됩니다. 공식 인증 문서는 로그인한 로컬 서버를 통해 클라우드 모델을 호출하는 예시도 제공합니다. 로컬 모델 실행과 클라우드 모델 이용은 데이터가 처리되는 위치가 다르므로, 앱에서 선택한 모델과 대상 서버를 함께 확인하세요.

응답이 없을 때 추가 점검

• 실제 Ollama 실행 상태와 설정된 OLLAMA_HOST를 확인하되, 이 글의 조회 예시와 설정 변경을 구분하세요.
• 앱이 Ollama API를 요구하는지 OpenAI 호환 API를 요구하는지 확인하세요. 공식 로컬 기본 URL은 각각 /api와 /v1로 다릅니다.
• FAQ는 HTTP_PROXY가 클라이언트와 서버 연결을 방해할 수 있다고 안내합니다. 회사 프록시 환경이라면 관련 설정을 확인하세요.
• 문제가 계속되면 FAQ가 연결한 공식 Troubleshooting 문서에서 로그 확인 방법을 살펴보세요. 설치 사양이나 오류 원인은 이 글만으로 단정하지 않습니다.

자주 묻는 질문

Q1. 로컬 모델 목록 조회에도 API 키가 필요한가요?

공식 문서상 로컬 API 자체는 인증을 요구하지 않습니다. 직접 ollama.com API를 호출하는 경우와 혼동하지 마세요.

Q2. 모델 목록이 보이면 추론도 정상인가요?

별개입니다. /api/tags는 사용 가능한 모델 목록 조회이며, 답변 생성의 성공 여부를 확인하는 요청이 아닙니다.

Q3. 버전 문서 주소도 /api/version인가요?

실제 요청 경로는 /api/version이지만, 확인일 기준 공식 설명 페이지는 /api-reference/get-version입니다. 문서 주소와 요청 URL을 구분하세요.

함께 보면 좋은 글

• 윈도우10·11 컴퓨터 사양 확인 방법: 모델 구동 조건을 비교할 때 실제 PC 사양을 먼저 확인하세요.
• 맥북 사양 확인 방법: 칩·메모리와 macOS 정보를 기록할 때 참고하세요. 이 두 글은 Ollama 최소 사양을 보증하지 않습니다.

공식 출처

• API Introduction: 기본 주소와 API 구분
• Authentication: 로컬·클라우드 인증
• List models: GET /api/tags
• Get version: GET /api/version
• FAQ: 기본 바인딩·환경 변수·프록시