Claude Code에서 Ollama 모델 사용하는 방법

개요

Claude Code는 터미널에서 동작하는 에이전틱 코딩 도구로, 작업 디렉터리의 코드를 읽고 수정하고 실행까지 할 수 있습니다. Ollama는 Anthropic Messages API와 호환되는 엔드포인트를 제공하므로, Claude Code가 기대하는 "Anthropic API" 자리에 Ollama를 붙여 로컬/클라우드 모델을 Claude Code에서 바로 쓸 수 있습니다.¹²

로컬에서 qwen3-coder, glm-4.7, gpt-oss 같은 오픈 모델을 사용하거나, glm-4.7:cloud 같은 Ollama Cloud 모델도 같은 방식으로 연결됩니다.¹²

이미지 출처: Claude Code - Ollama

사전 준비

Ollama가 설치되어 있고(기본 포트 11434), 사용할 모델을 내려받을 수 있어야 합니다. 예를 들어 코딩 모델로는 다음이 자주 추천됩니다: qwen3-coder, glm-4.7, gpt-oss:20b.¹²

로컬 모델은 먼저 pull이 필요합니다.

ollama pull qwen3-coder

Claude Code도 설치되어 있어야 합니다.¹

가장 쉬운 설정: ollama launch claude

Ollama는 Claude Code용 자동 설정/실행 명령을 제공합니다.

ollama launch claude

이 명령은 모델 선택을 안내하고, Claude Code가 Ollama(Anthropic 호환 API)를 바라보도록 필요한 설정을 자동으로 구성한 뒤 실행합니다.¹²

실행은 하지 않고 설정만 하고 싶다면 다음처럼 합니다.

ollama launch claude --config

수동 설정: Anthropic 호환 API로 연결하기

Claude Code는 Ollama의 "Anthropic Messages API 호환" 엔드포인트(/v1/messages)에 연결하는 방식으로 동작합니다. 핵심은 Claude Code가 참조하는 환경 변수(Anthropic 계열)를 Ollama로 바꿔 주는 것입니다.¹²

셸에 아래 환경 변수를 설정합니다.

export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL=http://localhost:11434

그 다음 Claude Code를 Ollama 모델 이름으로 실행합니다.

claude --model gpt-oss:20b

원하면 환경 변수를 한 줄로 붙여 실행할 수도 있습니다.

ANTHROPIC_AUTH_TOKEN=ollama ANTHROPIC_BASE_URL=http://localhost:11434 ANTHROPIC_API_KEY="" claude --model qwen3-coder

모델 선택 팁(로컬/클라우드)

로컬에서는 qwen3-coder(코딩 특화), gpt-oss:20b(범용) 같은 모델이 추천됩니다.²

클라우드 모델도 동일한 --model로 지정해 사용할 수 있습니다. 예:

claude --model glm-4.7:cloud

Ollama Cloud는 별도 pull 없이 바로 사용 가능한 모델이 있습니다.¹²

컨텍스트 길이(중요)

Claude Code는 큰 컨텍스트 윈도우가 필요하므로 최소 32K~64K 토큰 이상을 권장합니다.¹³ 로컬 모델은 Ollama의 컨텍스트 길이 설정을 조정해야 할 수 있고, 클라우드 모델은 항상 최대 컨텍스트로 실행된다고 안내됩니다.³

이미지 출처: Claude Code with Anthropic API compatibility

Anthropic 기본 모델명에 맞춰야 하는 경우(별칭 만들기)

일부 도구/설정이 claude-3-5-sonnet 같은 "기본 Anthropic 모델명"을 전제로 할 때가 있습니다. 이 경우 Ollama에서 모델 이름을 복사해서 별칭을 만들 수 있습니다.²

ollama cp qwen3-coder claude-3-5-sonnet

이후 claude --model claude-3-5-sonnet처럼 지정하거나, API 요청의 model 필드에 그 이름을 넣어 사용할 수 있습니다.²

참고

¹Claude Code - Ollama

²Anthropic compatibility - Ollama

³Claude Code with Anthropic API compatibility