Claude Code에 Ollama 로컬 모델을 연결하고 클라우드로 되돌리는 방법

Claude Code는 Ollama의 Anthropic 호환 API를 통해 로컬 모델을 사용할 수 있습니다. 그러나 채팅 답변이 정상이라는 사실만으로 coding agent 작업까지 준비됐다고 볼 수는 없습니다. 실제 코드를 맡기기 전에 모델이 도구 호출을 지원하는지, 컴퓨터가 최소 64k 컨텍스트를 유지할 수 있는지, 작업을 명령과 diff로 검증 가능한 작은 범위로 제한할 수 있는지 확인해야 합니다.

이 안내서는 언제든 원상복구할 수 있는 경로를 사용합니다. Ollama 공식 방식으로 Claude Code를 qwen3.5에 연결하고, 단일 파일 승인 테스트를 실행하며, 추론이 실제로 로컬에서 이뤄지는지와 API·데이터 경계를 확인합니다. 마지막에는 로컬 override를 제거하고 클라우드 endpoint로 돌아갑니다. 아래 명령은 macOS, Linux, WSL의 Bash 기준입니다. 독자가 직접 실행할 절차이며, 이 글이 독자의 하드웨어에서 테스트를 수행했다는 뜻은 아닙니다.

먼저 결정하기: 로컬, 클라우드, 하이브리드

로컬 모델은 범위가 명확하고 결과를 기계적으로 검증할 수 있는 작업에 가장 잘 맞습니다. 대규모 저장소, 서비스 간 마이그레이션, 복잡한 디버깅은 작은 로컬 모델을 심하게 CPU offload하는 것보다 클라우드 모델이 더 실용적인 경우가 많습니다.

작업	권장 시작 경로	이유
단일 파일 수정, 테스트 하나 추가, 지역 함수 설명	로컬부터 시험	컨텍스트가 제한되고 명령과 diff로 확인 가능
의존성이 명확한 소·중형 모듈	로컬 또는 하이브리드	smoke test를 통과한 뒤 범위를 점진적으로 확대 가능
대형 monorepo, 서비스 간 refactor, 복잡한 조사	클라우드부터	더 큰 유효 컨텍스트와 안정적인 도구 계획 필요
64k 유지에 큰 CPU offload가 필요	클라우드부터	지연과 멈춤이 로컬 경로의 장점을 상쇄
prompt caching, Batches API, PDF 블록, 정확한 token 계산이 필요	클라우드부터	Ollama는 현재 Anthropic Messages API 일부만 구현
소스 코드를 원격 모델에 보낼 수 없음	cloud 기능을 끄고 로컬	web tools, MCP server, shell command의 네트워크는 별도 감사 필요

실용적인 하이브리드 정책은 작고 반복 검증 가능한 변경은 로컬에서 처리하고, 저장소 전체 추론, 미지원 API 기능, 반복되는 로컬 실패는 명시적으로 클라우드로 넘기는 것입니다. Claude Code 인터페이스는 하나로 유지하되 두 backend의 동작이 같다고 가정하지 않습니다.

1단계: 도구 지원 모델을 고르고 64k 컨텍스트 확보하기

Claude Code에는 텍스트 생성 이상의 능력이 필요합니다. 파일을 읽고 수정 사항을 적용하고 명령을 실행하려면 모델이 도구 호출을 안정적으로 생성해야 합니다. Ollama의 Qwen3.5 모델 페이지는 tools 지원과 Claude Code 실행 명령을 제공합니다. 실제로 pull한 모델은 Ollama model details API로도 확인할 수 있습니다.

모델을 pull하고 capabilities를 확인합니다.

ollama pull qwen3.5

curl http://localhost:11434/api/show \
  -H "Content-Type: application/json" \
  -d '{"model":"qwen3.5"}'

계속하기 전에 capabilities에 tools가 있는지 확인하세요. 없다면 일반 채팅 응답을 agent 검증으로 대신하면 안 됩니다. 현재 Ollama 라이브러리에서 도구 지원이 명시된 모델을 선택해 pull한 뒤 다시 확인합니다.

두 번째 관문은 컨텍스트입니다. Ollama의 context length 문서는 web search, agent, coding tool에 최소 64,000 tokens를 권장하며, 컨텍스트가 커질수록 메모리 요구량도 증가한다고 설명합니다. Ollama App에서는 context length를 64000 이상으로 설정합니다. shell에서 service를 시작한다면 기존 instance를 먼저 중지한 뒤 별도 terminal에서 실행합니다.

OLLAMA_CONTEXT_LENGTH=64000 ollama serve

이 terminal은 열린 상태로 둡니다. server가 시작될 때까지 기다린 뒤 두 번째 terminal에서 계속하세요. port가 이미 사용 중이라면 Ollama instance가 실행 중인 것이므로 두 번째 server를 시작하지 말고 기존 instance의 context 설정을 바꿉니다.

2단계: Ollama 공식 integration으로 Claude Code 시작하기

가장 짧은 공식 경로는 다음과 같습니다.

ollama launch claude --model qwen3.5

통합을 먼저 통과시키기에는 이 방식이 가장 간단합니다. Claude Code가 시작되면 /status를 실행하고 활성화된 settings source를 기록하세요. 클라우드로 돌아갔다고 생각했는데도 계속 Ollama로 연결될 때 남아 있는 영구 override를 찾는 데 도움이 됩니다.

변경을 현재 terminal에만 제한하려면 환경 변수를 직접 설정합니다. 아래도 Bash입니다.

read -rs ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_API_KEY=""
export ANTHROPIC_BASE_URL="http://localhost:11434"
claude --model qwen3.5

read -rs는 입력을 화면에 표시하지 않습니다. ollama를 입력하고 Enter를 누르세요. Ollama 호환 endpoint는 인증 변수가 존재해야 하지만 local server는 값을 검증하지 않습니다. ANTHROPIC_BASE_URL은 model request를 local Ollama로 보내고, --model qwen3.5는 테스트 모델을 명시하여 오래된 ANTHROPIC_MODEL이나 저장된 default가 결과를 흐리지 않게 합니다.

3단계: 단일 파일로 읽기·편집·명령 실행 검증하기

첫 로컬 모델 테스트에 운영 저장소를 사용하지 마세요. 파일, 종료 status, diff로 모든 결과를 볼 수 있는 격리 directory를 만듭니다.

mkdir -p claude-ollama-smoke
cd claude-ollama-smoke
git init
cat > total.py <<'PY'
def total(values):
    return sum(values)

if __name__ == "__main__":
    assert total([2, 3]) == 5
PY
git add total.py
python3 total.py

python3 total.py는 아무것도 출력하지 않고 status 0으로 끝나야 합니다. 이 directory에서 local Claude Code를 시작하고 다음 작업을 보냅니다.

total.py만 수정하세요.
values의 항목 중 int 또는 float가 아닌 값이 있으면 total이 TypeError를 발생시키고, 오류 메시지는 정확히 numbers only가 되게 하세요.
__main__에 [2, "3"]에 대한 검사를 추가하여 같은 TypeError와 메시지를 확인하세요.
python3 total.py를 실행하세요.
다른 파일은 수정하지 마세요. 완료 후 diff를 보여 주세요.

작업은 의도적으로 작지만 핵심 agent loop를 검증합니다. 기존 파일을 읽고, 변경을 계획하고, 편집 tool을 호출하고, Bash command를 요청하고, 결과를 관찰하고, 최종 차이를 보여 주는 흐름입니다. Claude Code의 permission prompt는 유지하세요. 모델이 로컬이라는 이유로 제한 없는 shell 실행이 안전해지지는 않습니다.

작업 후 직접 실행합니다.

python3 total.py
git status --short
git diff -- total.py
ollama ps

승인 기준은 다음과 같습니다.

1. python3 total.py가 status 0으로 종료됩니다.
2. git status --short에는 total.py만 나타나고, git diff -- total.py에는 요청한 타입 검사와 assertion만 있습니다.
3. Claude Code transcript에 파일·Bash tool 호출이나 permission request가 보이며, 코드 제안 문장만 나오지 않습니다.
4. 작업 중 ollama ps에 qwen3.5가 표시되고, CONTEXT가 최소 64000이며, PROCESSOR를 통해 전체 GPU, 부분 offload, 주로 CPU인지 확인할 수 있습니다.

하나라도 실패하면 실제 저장소로 범위를 넓히지 마세요. 먼저 뒤의 문제 해결 절차를 따르고 모델 변경, 작업 축소, cloud 전환 중 무엇이 필요한지 결정합니다.

4단계: localhost가 아니라 실제 실행 경계 확인하기

ANTHROPIC_BASE_URL=http://localhost:11434는 Claude Code가 model request를 local port로 보낸다는 사실을 보여 주지만 전체 workflow가 offline이라는 증거는 아닙니다. 더 강한 근거는 model tag에 :cloud가 없고, 작업 중 model이 ollama ps에 나타나며, local PROCESSOR와 CONTEXT 값이 장비 할당과 일치하는 조합입니다.

Ollama FAQ는 local 실행 시 Ollama가 prompt나 data를 보지 않지만 cloud-hosted model을 사용할 때는 prompt와 response가 cloud service에서 처리된다고 설명합니다. 현재 Qwen3.5 페이지의 Claude Code 명령은 local tag qwen3.5를 사용합니다. local tag에 suffix를 붙여 cloud model name을 추정하지 마세요. cloud boundary를 확인하려면 현재 공식 Cloud catalog나 integration guide에 명시된 유효한 tag인 gemma4:cloud 같은 예시를 사용합니다. 실제 실행 위치는 유효한 tag, ollama ps, local resource allocation으로 판단합니다.

다른 네트워크 경로도 별도로 감사하세요.

• Bash를 통해 호출된 command는 network에 접속하거나 file을 upload하거나 다른 CLI를 실행할 수 있습니다.
• MCP server에는 자체 process, permission, data route가 있습니다.
• web search, web fetch, Ollama cloud model은 local inference가 아닙니다.
• repository hooks, test script, package manager도 외부 service에 연결할 수 있습니다.

더 엄격한 Ollama local-only mode가 필요하면 기존 ~/.ollama/server.json의 다른 설정을 지우지 말고 다음 key를 합칩니다.

{
  "disable_ollama_cloud": true
}

Ollama를 재시작하고 log에 Ollama cloud disabled: true가 표시되는지 확인합니다. Ollama 문서상 이 설정은 cloud model과 web search를 비활성화합니다. 그러나 Claude Code, MCP server, shell command의 다른 네트워크 접근까지 감사하지는 않습니다.

5단계: 호환 layer가 보장하지 않는 범위 이해하기

Ollama는 Anthropic Messages API 호환 layer를 제공하며 Anthropic API 전체를 재구현하지는 않습니다. 현재 문서는 messages, streaming, system prompts, images, tool calls, tool results, thinking 등을 지원 기능으로 열거합니다. 기본 Claude Code agent loop를 구성하기에는 충분합니다.

protocol 지원은 동작의 동일성을 의미하지 않습니다. 도구 선택 품질, patch 정확도, 긴 작업의 안정성, 지시 준수는 모델, quantization, context 할당, hardware에 따라 달라집니다. 단일 파일 테스트 통과는 현재 환경에서 최소 경로가 작동한다는 뜻일 뿐, 대형 저장소에서 cloud Claude model과 동등하다는 증거가 아닙니다.

Ollama는 현재 /v1/messages/count_tokens, prompt caching, Batches API, citations, PDF document block, streaming 중 server-sent errors를 미지원으로 안내합니다. token count도 기반 모델 tokenizer에 따른 근사치입니다. 작업이 이런 기능에 의존한다면 중간에 한계를 발견하기 전에 cloud 경로를 준비해 둡니다.

6단계: 남은 설정 없이 명시적으로 클라우드로 복귀하기

local 변수를 현재 Bash session에서만 설정했다면 Claude Code를 종료하고 실행합니다.

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_API_KEY ANTHROPIC_MODEL ANTHROPIC_DEFAULT_HAIKU_MODEL ANTHROPIC_DEFAULT_SONNET_MODEL ANTHROPIC_DEFAULT_OPUS_MODEL
claude

새 process는 일반적인 account login 또는 cloud provider 설정을 따를 수 있습니다. 시작 후 /status를 확인하고 작은 read-only question을 하나 보냅니다. client가 실행됐다는 사실만으로 cloud request가 완료됐다고 판단하면 안 됩니다.

그래도 Claude Code가 Ollama에 연결된다면 override가 current shell이 아니라 settings에 저장됐을 가능성이 큽니다. Claude Code 공식 환경 변수 문서는 settings file의 env 값이 shell에서 물려받은 같은 이름의 변수를 덮어쓴다고 설명합니다. /status로 active source를 확인하고 해당 layer에서 local ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, model override를 제거합니다.

• ~/.claude/settings.json
• .claude/settings.json
• .claude/settings.local.json
• 조직이 배포한 managed settings

수정 후 Claude Code를 완전히 종료하고 다시 시작합니다. managed value는 하위 layer로 무효화할 수 없으므로 administrator가 변경해야 합니다.

local model이 작업에 맞지 않지만 같은 Claude Code에서 Anthropic 호환 cloud API를 사용하고 싶다면 현재 BetterToken Claude Code 문서를 따를 수 있습니다. 현재 Base URL은 https://bettertoken.ai이며 www도 /v1도 붙지 않습니다. 먼저 model plaza에서 정확한 Model ID를 복사합니다. 현재 manual setup은 ANTHROPIC_MODEL로 primary model을 지정하고 세 개의 ANTHROPIC_DEFAULT_*_MODEL 변수로 Haiku, Sonnet, Opus alias를 매핑합니다. controlled smoke test에서는 네 변수를 모두 같은 정확한 ID로 지정할 수 있습니다. 다음 임시 Bash setup은 API Key를 command history에 남기지 않습니다.

read -rsp "BetterToken API Key: " ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_AUTH_TOKEN
read -rp $'\nBetterToken Model ID: ' ANTHROPIC_MODEL
export ANTHROPIC_MODEL
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
export API_TIMEOUT_MS="3000000"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_SONNET_MODEL="$ANTHROPIC_MODEL"
export ANTHROPIC_DEFAULT_OPUS_MODEL="$ANTHROPIC_MODEL"
claude

첫 번째 prompt는 API Key 입력을 숨기며, 두 번째 prompt에는 model plaza에서 복사한 정확한 Model ID를 붙여 넣습니다. 이 smoke test는 primary model과 세 alias를 모두 같은 ID로 지정합니다. 역할별로 다른 model을 사용할 때는 각 default 변수에 해당하는 정확한 ID를 별도로 설정하세요. Base URL 뒤에 /v1을 붙이지 않습니다. persistent settings를 바꾼 뒤에는 Claude Code를 완전히 종료하고 재시작해야 하며, temporary session에서도 이 block을 실행하기 전에 기존 process를 닫습니다. 마지막으로 짧은 read-only request를 하나 보냅니다. 정상 응답이 오고 401, connection 또는 model error가 없으며 /status가 예상한 active source를 표시할 때만 전환 완료로 판단합니다. 이는 local path와 cloud path의 모든 기능이 같다는 뜻이 아닙니다.

자주 발생하는 실패를 분리해 확인하기

ConnectionRefused 또는 localhost:11434 무응답

Ollama process가 실행 중인지, endpoint가 예상 port를 사용하는지 확인합니다. 필요하면 ollama serve로 시작합니다. port가 사용 중이면 두 번째 instance를 띄우지 말고 기존 instance를 찾습니다. Claude Code를 다시 열기 전에 curl http://localhost:11434/api/ps가 JSON을 반환하는지 확인합니다.

채팅은 되지만 Claude Code가 파일을 읽거나 편집하지 않음

/api/show를 다시 호출하여 model이 tools를 표시하는지 확인합니다. 이어서 Claude Code permission request가 나타나는지 봅니다. 모델이 “이렇게 바꿀 수 있습니다”라는 텍스트만 내고 tool call을 만들지 않으면 명시적으로 도구 지원 모델로 바꿉니다. tool field를 전달할 수 있다는 사실은 모든 모델의 tool planning 품질을 보장하지 않습니다.

매우 느리거나 긴 작업에서 context를 잃음

ollama ps를 실행하고 PROCESSOR와 CONTEXT를 확인합니다. 큰 CPU offload, 64k 미만 context, 반복되는 memory pressure는 작업을 줄이거나 더 작은 도구 지원 모델을 선택하거나 cloud를 사용할 이유입니다. 빠르게 보이게 하려고 permission과 검증을 제거하지 마세요.

shell 변수를 바꿔도 endpoint나 model이 변하지 않음

Claude Code에서 /status를 실행합니다. settings의 env 값은 shell 값을 대체할 수 있고, --model과 /model은 ANTHROPIC_MODEL보다 우선합니다. 실제로 우선하는 source를 정리하고 완전히 재시작한 뒤 read-only request를 반복합니다.

실무적인 결정 기준

local Claude Code를 단순한 toggle이 아니라 더 큰 범위를 맡기기 전에 검증해야 하는 실행 경로로 보세요. tools를 확인하고 최소 64k context를 할당하며, 단일 파일 작업으로 tool call, 종료 status, diff, ollama ps를 점검합니다. 이 신호가 안정된 뒤에만 범위를 늘립니다.

작업이 장비 한계를 넘거나, 미지원 Anthropic 기능이 필요하거나, local model이 실제 코드에서 반복 실패하면 local endpoint를 제거하고 의도적으로 cloud로 전환합니다. 모든 coding 작업을 억지로 local에 두는 것보다 확실한 rollback path를 갖는 편이 더 중요합니다.