Claude Code + 로컬 LLM 완전분석: API 비용 0원으로 돌리는 법

월말에 Claude API 비용 청구서 보고 식겁한 적 있으면 이 글이 딱입니다. 2026년 1월 Ollama v0.14.0부터 Anthropic Messages API를 네이티브로 지원하면서, 환경변수 두 줄로 Claude Code를 로컬 LLM에 연결할 수 있게 됐습니다. 프록시도, 미들웨어도 필요 없습니다.

---

핵심 요약

Claude Code는 내부적으로 Anthropic Messages API 포맷으로 요청을 보냅니다. 기본값은 Anthropic 서버지만, ANTHROPIC_BASE_URL을 바꾸면 같은 포맷을 받는 로컬 서버로 그대로 리다이렉트됩니다. Claude 모델인지 확인하는 검증 로직이 없기 때문에, Ollama가 띄워주는 로컬 서버로 향하게 하면 어떤 오픈소스 모델이든 Claude Code의 백엔드로 쓸 수 있습니다.

이게 가능해진 건 Ollama v0.14.0의 Anthropic API 네이티브 지원 덕분입니다. 이전에는 Flask 프록시를 따로 띄워서 API 포맷을 변환하는 방식이 필요했는데, 이제는 그런 복잡한 중간 단계가 전부 사라졌습니다.

 

로컬 실행의 가장 큰 장점은 두 가지입니다. 비용이 0원이고, 코드가 머신 밖으로 나가지 않습니다. 개발자 조사에서 64%가 코드를 클라우드에 보내는 것에 불안감을 느낀다고 답했는데, 로컬 모델은 이 문제를 완전히 해결합니다.

모델 선택이 성패를 가릅니다. Claude Code는 컨텍스트를 많이 쓰는 에이전트 루프 특성상 최소 64K 컨텍스트를 지원하는 모델이 필요합니다. 2026년 6월 기준 가장 많이 쓰이는 조합은 Qwen3.6:27b(SWE-bench 77.2%, 256K 컨텍스트)와 GLM-4.7-Flash(툴 호출 강점, 128K 컨텍스트)입니다. 32K 이하 모델은 복잡한 태스크에서 컨텍스트가 잘려서 제대로 동작하지 않습니다.

단점도 솔직하게 얘기하면, 클라우드 Claude Opus와 비교하면 품질 차이는 분명히 있습니다. 복잡한 아키텍처 결정이나 멀티파일 리팩토링에서는 차이가 납니다. 하지만 코드 설명, 보일러플레이트 생성, 간단한 디버깅처럼 일상적인 작업은 로컬 모델로 충분히 커버됩니다.

---

실전 1: 5분 안에 돌리기 — Ollama 기본 세팅

Ollama가 설치돼 있다면 정말 명령어 몇 줄입니다. 없으면 먼저 설치하고 시작합니다. 모델은 처음에 Qwen3.6:27b를 권장합니다. 2026년 4월 기준 Apache 2.0 라이선스에 SWE-bench 77.2%를 찍은 모델로, 대부분의 코딩 태스크에서 클라우드 Sonnet과 몇 포인트 차이 안 납니다.

# Ollama 설치 (macOS / Linux)
curl -fsSL https://ollama.com/install.sh | sh

# 모델 다운로드 (하드웨어별 선택)
# 24GB+ VRAM / 32GB+ 통합메모리 → 27B Dense 추천
ollama pull qwen3.6:27b

# 16GB VRAM / 24GB 통합메모리 → MoE 경량판
ollama pull qwen3.6:35b-a3b

# 8~16GB → GLM 빠른 버전
ollama pull glm-4.7-flash

# Ollama 서버 실행 확인
ollama serve  # 이미 실행 중이면 에러 나도 무시
curl http://localhost:11434/api/version  # {"version":"0.xx.x"} 나오면 OK

모델 다운로드가 완료되면 Claude Code와 연결합니다. ollama launch claude 한 줄로 환경변수 자동 설정 + Claude Code 실행까지 한 번에 됩니다. 수동으로 하고 싶다면 아래 방법을 씁니다.

# 방법 1: ollama launch (가장 간단, Ollama 0.23+ 필요)
ollama launch claude --model qwen3.6:27b

# 방법 2: 환경변수 직접 설정
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_AUTH_TOKEN="ollama"
export ANTHROPIC_API_KEY=""

# 모델 티어 매핑 (Claude Code가 내부적으로 sonnet/haiku/opus를 요청하므로 필수)
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen3.6:27b"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen3.6:27b"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen3.6:27b"

# Claude Code 실행
claude

프로젝트 폴더로 이동한 뒤 claude를 치면 됩니다. /init을 입력하면 Claude Code가 코드베이스를 스캔하고 CLAUDE.md를 생성합니다. 이후 사용법은 클라우드 버전과 완전히 동일합니다.

---

실전 2: 영구 설정 — 매번 export 안 하는 법

터미널을 새로 열 때마다 환경변수를 다시 입력하는 건 귀찮습니다. ~/.claude/settings.json에 한 번 박아두면 Claude Code가 시작할 때마다 자동으로 읽습니다.

// ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "qwen3.6:27b",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.7-flash",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "qwen3.6:27b"
  }
}

Haiku 티어에 GLM-4.7-Flash를 따로 매핑하는 이유가 있습니다. Claude Code는 빠른 응답이 필요한 단순 태스크에 Haiku를 자동으로 요청하는데, GLM-4.7-Flash가 툴 호출에서 특히 강하고 응답 속도가 빠르기 때문입니다. Sonnet과 Opus는 더 무거운 작업에 27B로 처리하는 조합이 실용적입니다.

클라우드 Claude로 잠깐 전환하고 싶을 때를 위해 .zshrc나 .bashrc에 함수 두 개를 등록해두면 편합니다.

# ~/.zshrc 또는 ~/.bashrc에 추가

# 로컬 모드로 전환
claude-local() {
  export ANTHROPIC_BASE_URL="http://localhost:11434"
  export ANTHROPIC_AUTH_TOKEN="ollama"
  export ANTHROPIC_API_KEY=""
  export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen3.6:27b"
  export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash"
  export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen3.6:27b"
  echo "✓ 로컬 모드 (Ollama)"
}

# 클라우드 모드로 전환
claude-cloud() {
  unset ANTHROPIC_BASE_URL
  unset ANTHROPIC_AUTH_TOKEN
  unset ANTHROPIC_DEFAULT_SONNET_MODEL
  unset ANTHROPIC_DEFAULT_HAIKU_MODEL
  unset ANTHROPIC_DEFAULT_OPUS_MODEL
  export ANTHROPIC_API_KEY="sk-ant-..."  # 실제 키
  echo "✓ 클라우드 모드 (Anthropic)"
}

같은 터미널 세션에서 claude-local, claude-cloud를 번갈아 치면 즉시 전환됩니다. 일상 작업은 로컬로 돌리다가 복잡한 태스크만 클라우드로 빠르게 넘기는 패턴에 딱 맞습니다.

---

실전 3: Apple Silicon 최적화 — Rapid-MLX

M 시리즈 맥에서 Ollama로 돌리면 속도가 기대보다 느릴 수 있습니다. 특히 2+2 같은 단순한 질문도 30초 넘게 걸린다는 경험담이 많습니다. Rapid-MLX가 이 문제를 해결하는데, Ollama 대비 4.2배 빠른 추론 속도와 0.08초 첫 토큰 응답 시간을 주장합니다.

Claude Code의 에이전트 루프는 툴 호출이 빈번해서 응답 속도가 전체 체감에 직접 영향을 미칩니다. Apple Silicon 환경에서 느리다고 포기하기 전에 Rapid-MLX부터 시도해볼 만합니다.

# Rapid-MLX 설치 (macOS, Apple Silicon 전용)
brew install raullenchai/rapid-mlx/rapid-mlx

# 모델 실행
rapid-mlx serve qwen3-coder --port 8000

# Claude Code 연결
unset ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_AUTH_TOKEN="rapid-mlx"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen3-coder"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen3-coder"

claude

Rapid-MLX는 Ollama보다 커뮤니티가 작아서 엣지 케이스에서 에러가 더 자주 납니다. M3 Pro 이하에서는 Ollama 자체 최적화만으로도 충분한 경우가 많으니, M3 Max 이상에서 속도에 민감한 분들에게 추천합니다.

---

실전 4: 하드웨어별 모델 선택 가이드

어떤 모델을 고를지가 로컬 세팅의 핵심입니다. 컨텍스트 창이 너무 짧거나 툴 호출이 불안정한 모델은 Claude Code의 에이전트 루프에서 제대로 동작하지 않습니다.

RTX 4090(24GB VRAM) 또는 M2 Max(32GB 통합메모리)라면 qwen3.6:35b-a3b가 최선입니다. MoE 구조라 22GB에 돌아가면서 코딩 성능은 27B Dense와 비슷합니다. RTX 3090(24GB) 또는 M2 Pro(16~24GB)는 glm-4.7-flash가 현실적인 선택입니다. 툴 호출이 안정적이고 128K 컨텍스트를 지원해서 Claude Code와 잘 맞습니다. 8~16GB 환경이라면 qwen3.6:35b-a3b의 Q2 양자화나 qwen2.5-coder:7b로 내려가야 하지만 품질 저하가 체감됩니다.

# GPU VRAM 확인
nvidia-smi --query-gpu=name,memory.total --format=csv

# Apple Silicon 통합 메모리 확인
system_profiler SPHardwareDataType | grep Memory

# 모델 메모리 사용량 확인 (실행 후)
ollama ps

Claude Code가 컨텍스트를 잘라버리는 증상이 나타나면 모델의 컨텍스트 길이 설정을 늘려야 합니다. Ollama는 기본값이 모델마다 다르므로 아래처럼 명시적으로 지정하는 게 안전합니다.

# Modelfile로 컨텍스트 길이 강제 지정
cat > Modelfile << 'EOF'
FROM qwen3.6:27b
PARAMETER num_ctx 65536
EOF

ollama create qwen3.6-64k -f Modelfile
ollama run qwen3.6-64k

---

실전 5: 문제 해결

자주 나오는 에러와 해결책입니다. 처음 세팅할 때 막히는 지점 대부분이 여기에 해당합니다.

Claude Code가 모델을 찾지 못한다는 에러가 나면 ANTHROPIC_DEFAULT_SONNET_MODEL 설정이 빠진 겁니다. Claude Code가 내부적으로 claude-sonnet-4-20250514 같은 모델명을 요청하는데, 로컬 서버에 그 이름이 없으면 거절됩니다. 환경변수로 티어 이름을 로컬 모델명에 매핑해줘야 합니다.

# 에러: 모델을 찾을 수 없음
# 원인: 티어 매핑 없음
# 해결:
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen3.6:27b"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.7-flash"

# 에러: Connection refused
# 원인: Ollama 서버가 꺼져 있음
# 해결:
ollama serve  # 백그라운드로 실행
# 또는
ollama start  # 시스템 서비스로 등록된 경우

# 에러: 응답이 너무 느림 (30초+)
# 원인: GPU 가속이 안 되고 CPU로 돌아감
# 확인:
ollama ps  # SIZE: 옆에 GPU 표시 있으면 GPU 사용 중

# 에러: context window exceeded
# 해결: 컨텍스트 길이 늘리기
# Modelfile에 PARAMETER num_ctx 65536 추가

/cost 명령어로 현재 세션의 토큰 사용량을 확인할 수 있는데, 로컬 모드에서는 항상 0으로 나옵니다. 이게 정상입니다.

---

마무리

2026년 기준으로 Claude Code + 로컬 LLM은 "해볼 수 있는 실험" 수준을 넘어 실제 개발 워크플로우에 쓸 수 있는 선택지가 됐습니다. Ollama의 Anthropic API 네이티브 지원이 그 전환점이었고, Qwen3.6이나 GLM-4.7-Flash 같은 모델의 품질 향상이 나머지를 채웠습니다. 클라우드 Opus를 완전히 대체하기는 어렵지만, 일상적인 코딩 작업의 70~80%는 로컬로 커버하고 무거운 태스크만 클라우드로 넘기는 하이브리드 전략이 현재로서 가장 현실적입니다. 코드를 외부로 보내기 꺼려지는 상황이라면 더더욱 로컬 모드가 답입니다.

---