Claude Code 로컬 LLM 연결은 2026년 11월 현재 환경변수 두 줄로 끝납니다. Ollama v0.14와 LM Studio 0.4.1이 Anthropic Messages API를 직접 받아주기 때문입니다. 다만 모델을 잘못 고르면 “답은 하는데 파일을 안 고치는” 상태가 되고, 노트북 기본 설정에서는 첫 요청부터 400 오류로 죽습니다. 공개 실측 데이터를 기준으로 VRAM별로 실제로 되는 모델과 안되는 모델을 판정하고, 구독료와의 월 비용 손익분기까지 계산합니다.
Claude Code 로컬 LLM 연결, 왜 올해 가능해졌나
Claude Code는 터미널에서 도는 에이전트형 코딩 도구로, 모든 요청을 Anthropic Messages API(/v1/messages)로 보냅니다. 예전에는 로컬 서버가 OpenAI 형식만 지원해서 변환 프록시가 필요했지만, 2026년부터 주요 로컬 서버가 이 형식을 네이티브로 받기 시작했습니다.
| 서버 | 엔드포인트 | 기본 주소 | 버전·시점 |
|---|---|---|---|
| Ollama | /v1/messages | http://localhost:11434 | v0.14.0 (2026-01-16), ollama launch claude는 v0.15+ |
| LM Studio | /v1/messages (GGUF·MLX 모두) | http://localhost:1234 | 0.4.1 (2026-01-30) |
| llama.cpp llama-server | /v1/messages + /v1/messages/count_tokens | 포트 9931 (b11521부터, 이전 8080) | build b11521 (2026-10-09) |
| vLLM | Anthropic Messages API | http://localhost:8000 | –enable-auto-tool-choice + –tool-call-parser 필요 |
주의할 점: Anthropic 공식 게이트웨이 문서는 “비Claude 모델 라우팅을 지원하지 않는다”고 명시합니다. 동작은 하지만 공식 지원 밖이고, Claude Code 신규 릴리스가 로컬 서버가 못 받는 필드를 보내면 버그는 직접 고쳐야 합니다.
설정 3분 — 환경변수 두 줄과 필수 변수
export ANTHROPIC_BASE_URL=http://localhost:11434
export ANTHROPIC_AUTH_TOKEN=ollama
export ANTHROPIC_API_KEY=""
claude --model gpt-oss:20b여기서 끝이 아니라, 실전에서는 세 개를 더 지정해야 합니다. Claude Code는 백그라운드 작업에 haiku 별명을 쓰는데 매핑하지 않으면 세션 도중 404가 납니다. 또 모르는 모델 이름에는 200K 컨텍스트를 가정하므로(2.1.193부터) 서버에 실제로 실은 값과 맞춰줘야 합니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-oss:20b
export ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-oss:20b
export ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-oss:20b
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=32768서버가 OpenAI 형식만 지원하는 구형 환경에서는 Claude Code Router(구독형 아님, MIT 라이선스 v3.1.3, 2026-10-09, 포트 3456)나 LiteLLM(포트 4000)을 중간에 둘 수 있습니다. 다만 두 프록시 모두 모든 프롬프트와 파일 발췌를 통과하므로 localhost 외 바인딩은 피하세요. 서버가 처음이면 Ollama 설치부터 모델 삭제까지 가이드가 선행 단계입니다.
실제로 되는 모델·안되는 모델 — VRAM별 판정표
24GB M4 Pro(32K 컨텍스트)에서 다시 돌린 공개 실측(Ollama 0.40 + Claude Code 2.1.302, 2026년 10월 개정)과 Ollama 공식 권장을 합친 판정표입니다.
| 모델 | 다운로드·네이티브 컨텍스트 | 32K 기준 로드 용량 | 판정 |
|---|---|---|---|
| gpt-oss:20b | 14GB · 128K | 12GB (GPU 전부) | 24GB에서 편집 작업 완수 — Ollama 공식 권장 |
| qwen3-coder (30B-A3B) | 19GB급 · 256K | 19GB (24GB에서 GPU 16GB + CPU 분할) | 되지만 체감 둔화 — 32GB 이상 권장 |
| qwen3.8:27b (dense) | 18GB · 128K+ | Claude Code의 약 20K 토큰 시스템 프롬프트 진입 즉시 OOM | 24GB에서는 불가 — 32GB 이상 필요 |
| gemma4 12B / qwen3.5:9b | 약 8GB급 | 16K 컨텍스트 기준 16GB 이내 | 16GB 카드의 현실 선택지 |
| 도구 호출 미지원 소형 채팅 모델 | – | – | 말만 하고 행동 안 함 — ollama show의 Capabilities에 tools 확인 |
“답은 나오는데 파일을 안 고친다” — 도구 호출이 전부
Claude Code는 매 턴마다 파일 읽기·검색·편집·명령 실행을 도구 호출로 수행합니다. 채팅 점수가 높아도 잘-formed된 도구 호출을 못 만드는 모델은 첫 단계에서 멈칩니다. “답변은 오는데 파일 변경이 없다”면 모델 교체 외 해결책이 없습니다.
구체적 함정 하나: 2026년 3월 r/LocalLLaMA PSA에서 보고된 대로, LM Studio의 파서가 Qwen3.5 계열 도구 호출을 조용히 깨뜨립니다 — 툴 콜이 평문 텍스트로 반환되고 편집 도구가 침묵 no-op합니다. vLLM도 –tool-call-parser를 모델에 맞게 지정하지 않으면 같은 증상이 납니다. 설정 후 반드시 “특정 파일 고쳐봐” 한 줄로 실습해 검증하세요.
Claude Code 로컬 LLM 연결이 첫 요청에서 죽는 이유 — 컨텍스트 4K 함정
Ollama는 GPU 메모리 크기로 기본 컨텍스트를 자동 결정합니다: 24GiB 미만이면 4K, 24~48GiB면 32K, 초과면 256K. 그런데 Claude Code는 시스템 프롬프트와 도구 정의만 약 20K 토큰을 씁니다. 즉 노트북(대부분 24GiB 미만)에서는 기본값 그대로면 첫 요청에서 400 컨텍스트 초과로 죽습니다.
OLLAMA_CONTEXT_LENGTH=32768 ollama serve
ollama ps # CONTEXT 열이 32768인지 확인Ollama 문서의 코딩 에이전트 권장은 64K, 실전 마지노선은 32K입니다. macOS 앱에서는 설정 슬라이더로, Linux systemd에서는 서비스 파일에 환경변수를 넣습니다.
속도가 API보다 체감상 느린 것도 정상입니다. Ollama의 Anthropic 호환 엔드포인트는 프롬프트 캐싱(cache_control)과 토큰 카운팅 엔드포인트를 지원하지 않아, 매 턴 20K 토큰 프롬프트를 통째로 재처리합니다. forced tool_choice, URL 이미지, PDF도 미지원입니다.
구독 vs 로컬 — 월 비용 손익분기 계산
| 구분 | 가격 (USD) | 원화 환산 (1,334.30원 기준) |
|---|---|---|
| Pro (월간 결제) | $20/월 | 약 26,686원 |
| Pro (연간 결제) | $17/월 | 약 22,683원 |
| Max 5x | $100/월 | 약 133,430원 |
| Sonnet 5 API | 입력 $2 / 출력 $10 (MTok당, 2026-08-11 영구 확정) | 입력 약 2,669원 / 출력 약 13,343원 |
에이전트 헤비 유저 시나리오를 계산해 보면: 하루 100턴, 매 턴 입력 약 20K 토큰(캐싱 없음), 출력 평균 500토큰이면 하루 입력 2M 토큰 = $2.0, 출력 50K 토큰 = $0.5, 일 $2.5 × 30일 = 월 $75 ≈ 100,073원입니다. 이 구간에서는 Pro 구독(월 약 26,700원)이 API 종량보다 싸고, 로컬은 전기세(GPU 전기세 실측 — 월 27,000원부터)와 하드웨어 감가만으로 돕니다. 하루 20턴 이하의 가벼운 사용이라면 구독이 이기고, 헤비 사용 + 사내 코드 비공개 요건이 생기면 로컬이 이깁니다.
예산별 세팅 추천 — 학생·연구실·직장인
자체 스캔 시세(2026-11-06 15:02 KST, 최저가 기준)로 GB당 단가를 계산했습니다.
| 카드 | 최저가 | VRAM | GB당 단가 (계산) |
|---|---|---|---|
| RTX 5070 12GB | 1,199,000원 (n=11) | 12GB | 99,917원 (1,199,000 ÷ 12) |
| RX 9070 XT 16GB | 1,448,264원 (n=7) | 16GB | 90,517원 (1,448,264 ÷ 16) |
| RTX 5070 Ti 16GB | 1,579,000원 (n=10) | 16GB | 98,688원 (1,579,000 ÷ 16) |
| RTX 5080 16GB | 2,401,000원 (n=8) | 16GB | 150,063원 (2,401,000 ÷ 16) |
| RTX 4090 24GB (중고) | 3,800,000원 (n=2) | 24GB | 158,333원 (3,800,000 ÷ 24) |
| RTX 5090 32GB | 8,590,000원 (n=4) | 32GB | 268,438원 (8,590,000 ÷ 32) |
학생: RTX 5070 Ti 16GB + gemma4 12B 또는 qwen3.5:9b(16K 컨텍스트)가 현실 조합입니다. gpt-oss:20b는 16GB에서 KV 캐시와 함께 빠듯해지니 컨텍스트를 낮춰 시험하세요. 연구실: 중고 4090 24GB에서 gpt-oss:20b가 통째로 GPU에 올라 편집 작업까지 완수되는 것이 실측으로 확인됐고, dense 27B와 64K 컨텍스트까지 노리면 32GB(5090)급이고, 모델 크기별 처리량 근거는 GPU별 Qwen 27B 공개 실측 속도표에 있습니다. 직장인 개인: Pro 구독(월 약 26,700원)을 기본으로 하고, 사내 코드 유출 금지 규정이 있으면 로컬 세트로 전환하는 순서를 권합니다.
자주 묻는 질문
Claude Code가 로컬 모델을 공식 지원하나요?
아니요. Anthropic 게이트웨이 문서는 비Claude 모델 라우팅을 지원하지 않는다고 명시합니다. Ollama·LM Studio·vLLM이 각자 가이드를 내걸고 동작하므로 실무에서는 쓸 수 있지만, 문제는 그 프로젝트들이 받습니다.
Claude Code 로컬 LLM 연결에 필요한 최소 GPU 사양은?
VRAM 16GB + 컨텍스트 32K 설정이 실전 최소입니다. 4K 기본값 상태에서는 시스템 프롬프트 약 20K 토큰을 못 넣어 첫 요청부터 실패합니다.
왜 같은 GPU인데 API보다 느린가요?
Ollama 엔드포인트가 프롬프트 캐싱을 지원하지 않아 매 턴 약 20K 토큰을 재처리하기 때문입니다. 모델이 GPU에 안 맞아 CPU 분할되면 격차는 더 벌어집니다. ollama ps에서 CPU/GPU 분할 비율을 확인하세요.
Mac에서도 되나요?
됩니다. LM Studio 0.4.1은 MLX 모델에도 /v1/messages를 제공하고, 24GB M4 Pro 실측에서 gpt-oss:20b가 12GB(32K 컨텍스트)로 올라가 편집 작업까지 완료했습니다.
출처: Ollama 공식 블로그·문서(2026-01-16), LM Studio 0.4.1 공지(2026-01-30), llama.cpp README(b11521, 2026-10-09), Anthropic 게이트웨이 문서, CloudZero Claude 요금 정리(2026-09-14), 24GB M4 Pro 공개 실측(2026-10 개정). 국내 GPU 시세는 자체 스캔 2026-11-06 15:02 KST, 환율 1,334.30원(2026-10-30 기준). 가격·버전은 변동될 수 있습니다.
답글 남기기