Claude Code는 기본적으로 Anthropic 모델과 함께 제공되지만, 단일 환경 변수인 ANTHROPIC_BASE_URL만 설정하면 사실상 모든 LLM 제공자로 요청을 라우팅할 수 있습니다. 이는 Claude Opus의 백만 토큰당 $25 대신 DeepSeek을 약 백만 출력 토큰당 $0.27에 사용할 수 있음을 의미하며, Ollama를 통해 모델을 로컬에서 무료로 실행할 수도 있습니다. 이 가이드에서는 Claude Code 상세 비교 글을 바탕으로, 각 접근 방식의 실전 설정법을 포함하여 Claude Code에서 다양한 모델을 사용하는 모든 방법을 다룹니다.
한눈에 보는 모든 방법
상황에 맞는 방법을 선택한 후, 해당 섹션으로 이동하여 설정 코드를 확인하세요.
| 방법 | 적합한 경우 | 비용 | 설정 난이도 | 모델 |
|---|---|---|---|---|
| OpenRouter | 다양한 모델, 단일 API 키 | 토큰당 과금 (비용 전가) | 쉬움 | 300+ |
| Ollama | 프라이버시, 무료, 오프라인 | 무료 (자체 하드웨어) | 쉬움 | 50+ 오픈소스 |
| LM Studio | GUI가 있는 로컬 모델 | 무료 (자체 하드웨어) | 쉬움 | 50+ 오픈소스 |
| claude-code-router | 작업별 스마트 라우팅 | 제공자에 따라 다름 | 중간 | 설정에 따라 다름 |
| claude-code-proxy | Gemini/OpenAI 백엔드 | 제공자 가격 정책 | 중간 | OpenAI + Gemini |
| LiteLLM | 엔터프라이즈, 부하 분산 | 제공자 가격 정책 | 고급 | 제공자 간 100+ |
각 방법의 단계별 설정을 계속 읽어보거나, 이미 필요한 것을 알고 있다면 결정 프레임워크로 바로 이동하세요.
Claude Code 모델 전환은 실제로 어떻게 작동할까?
프록시를 구성하기 전에, 왜 대부분의 튜토리얼이 잘못된 설정으로 이어지는지 이해해야 합니다. Claude Code는 내부적으로 하나가 아닌 세 개의 모델 슬롯을 사용합니다:
- Haiku 슬롯: 파일 요약 및 탭 자동 완성 같은 배경 작업
- Sonnet 슬롯: 기본 코딩, 사용자가 가장 많이 상호작용하는 모델
- Opus 슬롯: 복잡한 추론, 계획 수립 및 다단계 에이전트 작업
/model 또는 --model로 모델을 변경할 때, 여러분은 주요 슬롯만 변경하는 것입니다. Claude Code는 여전히 Anthropic의 API를 사용하여 다른 두 슬롯을 호출하려고 시도합니다. ANTHROPIC_BASE_URL을 프록시로 지정했지만 하나의 모델만 설정했다면, 다른 슬롯들은 "model not found"(모델을 찾을 수 없음) 오류와 함께 실패합니다.
해결책: 모든 슬롯이 프록시를 통해 라우팅되도록 세 가지 환경 변수를 모두 설정하는 것입니다.
# Cut Claude Code's Bill 90%: Run OpenRouter, Ollama or LiteLLM
export ANTHROPIC_DEFAULT_HAIKU_MODEL="your-haiku-equivalent"
export ANTHROPIC_DEFAULT_SONNET_MODEL="your-sonnet-equivalent"
export ANTHROPIC_DEFAULT_OPUS_MODEL="your-opus-equivalent"네이티브 모델 전환 (Anthropic 모델)
Anthropic 모델 패밀리 내에서만 사용한다면 전환은 간단합니다. Claude Code 내부에서 /model 명령어를 사용하거나, 터미널에서 실행 시 --model을 전달하거나, 설정 파일의 availableModels 배열에 모델을 추가하면 됩니다. Anthropic은 여기서 옵션을 계속 추가하고 있으며, 최근 출시된 기능들은 2026년 최신 Claude Code 기능 roundup에서 확인할 수 있습니다.
opusplan 전략
**opusplan**은 Claude Code의 내장 멀티 모델 라우팅 기능입니다. 배경 작업은 Haiku로 보내고 복잡한 추론은 자동으로 Opus로 전달합니다. 이를 수동으로 구성할 필요 없이 모델로 선택하기만 하면 됩니다. 이는 "파일 목록 조회인데 왜 Opus 가격을 지불하지?"라는 문제에 대한 Anthropic 자체의 해결책입니다. 서드파티 라우터를 사용하기 전에, 속도가 우선순위라면 Anthropic의 fast mode와 함께 시도해 볼 가치가 있습니다.
OpenRouter, 하나의 API 키로 300개 이상의 모델
OpenRouter는 API 집계기 역할을 합니다. 단일 API 키 하나로 Anthropic, Google, Meta, Mistral, DeepSeek 등 300개 이상의 모델에 접근할 수 있습니다. 대부분의 모델 가격은 비용 전가(pass-through) 방식으로, 마크업이 없습니다.
설정 단계
- openrouter.ai에서 계정을 생성하고 API 키를 발급받습니다.
claude /logout을 실행하여 기존 Anthropic 세션을 초기화합니다.- 환경 변수를 설정합니다:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_API_KEY="sk-or-v1-your-key-here"
# Map all three model slots
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek/deepseek-chat-v3"
export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-4"
export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-4"claude를 실행하고 연결을 확인합니다.
위의 세 가지 슬롯 변수를 주의 깊게 확인하세요. 이를 건너뛰면 앞서 언급한 "model not found" 오류가 발생합니다. 공식 OpenRouter 통합 가이드에서도 이 설정을 확인할 수 있습니다.
OpenRouter 권장 모델
OpenRouter의 모든 모델이 Claude Code의 도구 호출(tool calling)을 안정적으로 처리하는 것은 아닙니다. 실제로 잘 작동하는 모델들은 다음과 같습니다:
| 작업 | 모델 | 이유 |
|---|---|---|
| 저렴한 배경 작업 | DeepSeek V3.2 | 백만 토큰당 $0.27/$1.10, 괜찮은 도구 호출 성능 |
| 기본 코딩 | Claude Sonnet 4 | 직접 사용 시와 동일한 품질, 청구서 통합 |
| 대규모 코드베이스 (1M 컨텍스트) | Gemini 2.5 Flash | 백만 토큰당 $0.15/$0.60, 거대한 컨텍스트 윈도우 |
| 복잡한 추론 | Claude Opus 4 | 최고의 에이전트 코딩 품질 |
비용 및 청구
OpenRouter는 대부분의 모델에서 비용 전가 가격을 적용합니다. underlying 제공자가 청구하는 금액 exactly 그대로 지불하며, 일부 서드파티 모델에는 작은 마진이 추가됩니다. OpenRouter 대시보드에서 지출 한도를 설정하여 예상치 못한 비용을 방지하세요.
판단: OpenRouter는 최소한의 설정으로 최대한의 모델 다양성을 원하는 개발자에게 최고의 선택입니다. 하나의 API 키, 하나의 청구 대시보드, 300개 이상의 모델. 유연성 측면에서 비교 대상이 없습니다.
Ollama, 무료, 로컬, 그리고 프라이버시
Ollama는 모델을 완전히 사용자의 머신에서 실행합니다. v0.14.0(2026년 1월)부터 Anthropic Messages API를 네이티브로 지원하므로, Claude Code는 별도의 변환 계층 없이 Ollama와 통신할 수 있습니다. 코드가 머신 외부로 유출되지 않습니다.
필수 조건 및 하드웨어
사용 가능한 경험을 위해 적절한 하드웨어가 필요합니다:
- 7B 모델 (빠른 편집, 간단한 작업): 최소 16GB RAM
- 14B 모델 (견고한 코딩 품질): 32GB RAM, GPU 권장
- 32B+ 모델 (클라우드 수준 품질): 64GB RAM 또는 24GB+ VRAM 전용 GPU
하드웨어 요구 사항 및 모델 선택에 대한 더 깊은 탐색은 LLM 로컬 실행 가이드를 확인하세요.
설정 단계
- ollama.com에서 Ollama를 설치합니다.
- 코딩 중심 모델을 풀(pull)합니다.
- Claude Code 호환 모드로 실행합니다.
- 환경 변수를 설정합니다.
# Install and pull a coding model
ollama pull qwen2.5-coder:14b
# Launch with Claude Code compatibility
ollama launch claude
# Set env vars
export ANTHROPIC_BASE_URL="http://localhost:11434"
export ANTHROPIC_API_KEY="ollama"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen2.5-coder:14b"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen2.5-coder:14b"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen2.5-coder:14b"Ollama 통합 문서는 최고의 Claude Code 경험을 위해 64k+ 토큰 컨텍스트 윈도우를 가진 모델을 권장합니다.
코딩을 위한 최고의 로컬 모델
| 모델 | 크기 | 강점 | 비고 |
|---|---|---|---|
| Qwen 2.5 Coder 14B | 14B | 전체적인 로컬 코딩 최고 | 강력한 도구 호출, 우수한 컨텍스트 처리 |
| devstral | 24B | Mistral의 코딩 전문가 | 리팩토링 및 코드 리뷰에 우수 |
| GLM 4.7 | 9B | 일반 추론 | 속도와 품질의 좋은 균형 |
한 가지 사실에 대해 솔직해져야 합니다: 로컬 모델은 복잡하고 다단계인 에이전트 작업에서 Claude Sonnet보다 noticeably 낮은 품질의 코드를 생성합니다. 도구 호출의 신뢰성이 낮으며, 존재하지 않는 파일 경로(hallucinated file paths)를 더 자주 볼 수 있습니다. 빠른 편집, 단순 생성 및 프라이버시가 중요한 작업에는 훌륭하지만, 50개 파일 리팩토링에서 네이티브 Claude 수준의 품질을 기대해서는 안 됩니다.
판단: Ollama는 프라이버시에 민감한 작업과 무료 무제한 사용을 원하는 개발자에게 최고의 선택입니다. 하드웨어가 있다면 "영원히 제로 달러"라는 주장을 반박하기 어렵습니다.
Ollama Cloud vs OpenRouter: 가격 및 각각의 우위 상황
Ollama와 OpenRouter는 비용 문제를 서로 반대쪽 끝에서 해결합니다. Ollama는 사용자가 제어하는 하드웨어에서 모델을 실행하여 토큰당 비용이 제로인 반면, OpenRouter는 관리할 하드웨어 없이 300개 이상의 호스팅 모델에 대해 비용 전가 가격을 청구합니다. 이 가이드는 Ollama를 로컬에 설정하는 방법을 다루지만, 호스팅 티어를 실행하는 경우에도 동일한 고정 비용 대 토큰당 비용 계산이 적용됩니다.
| 요소 | Ollama | OpenRouter |
|---|---|---|
| 비용 모델 | 로컬 무료, 하드웨어 비용 부담 | 토큰당 비용 전가, 대부분 모델 마크업 없음 |
| 예시 가격 | 토큰당 $0 | DeepSeek V3.2 백만 토큰당 $0.27/$1.10, Gemini 2.5 Flash 백만 토큰당 $0.15/$0.60 |
| 하드웨어 | 16GB RAM (7B) ~ 24GB+ VRAM (32B+) | 없음, 완전 호스팅 |
| 모델 접근 | 50+ 오픈소스 모델 | 제공자 간 300+ |
| 프라이버시 | 코드가 머신 외부로 유출되지 않음 | 요청이 OpenRouter를 통과함 |
프라이버시, 오프라인 사용, 또는 고빈도 루틴 편집이 중요하고 이미 하드웨어를 보유하고 있다면 Ollama를 선택하세요. 모델 다양성, 초기 하드웨어 비용 없음, 사용한 만큼만 지불하는 청구 방식을 원한다면 OpenRouter를 선택하세요.
LM Studio, GUI가 있는 로컬 모델
LM Studio는 Ollama와 동일한 로컬 모델 실행 기능을 제공하지만 시각적 인터페이스를 갖추고 있습니다. GUI에서 모델을 검색하고, 클릭 한 번으로 양자화(quanitization) 수준을 선택하며, Claude Code를 연결하기 전에 채팅을 테스트할 수 있습니다. 하드웨어 요구 사항은 Ollama와 동일합니다. 러너를 비교 중이라면, LLM 로컬 실행을 위한 최고의 도구 가이드에서 장단점을 확인할 수 있습니다.
설정
- LM Studio를 다운로드하여 설치합니다.
- 코딩 모델(Qwen 2.5 Coder, devstral 등)을 검색하고 다운로드합니다.
- LM Studio 인터페이스에서 로컬 서버를 시작합니다.
- Claude Code를 해당 서버로 지정합니다:
# Point Claude Code to LM Studio's local server
export ANTHROPIC_BASE_URL="http://localhost:1234/v1"
export ANTHROPIC_API_KEY="lm-studio"
export ANTHROPIC_DEFAULT_SONNET_MODEL="your-loaded-model-name"시각적 설정 가이드를 선호한다면 스크린샷이 포함된 LM Studio 블로그의 walkthrough를 참고하세요.
판단: LM Studio는 로컬 모델 관리에 CLI보다 GUI를 선호하는 개발자에게 가장 적합합니다. ollama pull과 config 파일에 이미 익숙하다면 Ollama를继续使用하세요. 모델을 시각적으로 탐색하고 슬라이더로 설정을 조정하고 싶다면 LM Studio가 정답입니다.
claude-code-router, 스마트 모델 라우팅
claude-code-router는 Claude Code와 구성된 제공자 사이에서 로컬 프록시를 실행하는 npm 패키지입니다. 이 도구의 흥미로운 점은 **컨텍스트 인식 라우팅(context-aware routing)**으로, 저렴한 배경 작업은 DeepSeek으로, 기본 코딩은 Sonnet으로, 복잡한 추론은 Opus로 자동으로 전송할 수 있다는 것입니다.
이 프로젝트는 30k+ GitHub 스타를 보유하고 있으며, OpenRouter, DeepSeek, Gemini, Ollama, Groq, Volcengine, SiliconFlow 등을 제공자로 지원합니다.
설치 및 설정
npm install -g claude-code-router
claude-code-router init
claude-code-router startinit 명령어는 제공자와 모델 매핑을 정의하는 config.json을 생성합니다:
{
"providers": {
"openrouter": {
"apiKey": "sk-or-v1-...",
"models": {
"haiku": "deepseek/deepseek-chat-v3",
"sonnet": "anthropic/claude-sonnet-4",
"opus": "anthropic/claude-opus-4"
}
}
}
}컨텍스트 인식 라우팅 구성
이 부분이 claude-code-router의 빛나는 점입니다. 복잡도에 따라 다양한 작업 유형을 다른 모델로 라우팅할 수 있습니다. 배경 요약은 저렴한 모델로, 계획 및 아키텍처 작업은 최상의 모델로 전달됩니다. 라우터는 모든 슬롯 매핑을 투명하게 처리합니다.
제공자를 혼합하여 사용할 수도 있습니다. 프라이버시에 민감한 저장소는 Ollama를 사용하고 나머지는 OpenRouter를 사용하며, Claude Code 내부의 /model 명령어로 전환할 수 있습니다.
판단: claude-code-router는 각 작업 유형을 처리할 모델을 세밀하게 제어하려는 파워 유저에게 가장 적합합니다. 가장 구성 가능한 옵션이지만, 이러한 유연성은 간단한 ANTHROPIC_BASE_URL 교체보다 더 많은 설정을 필요로 합니다.
claude-code-proxy 및 LiteLLM, 고급 설정
이 두 방법은 서로 다른 Needs를 충족시키지만 한 가지 공통점이 있습니다: 둘 다 API 형식 간을 변환하는 프록시 서버라는 점입니다.
claude-code-proxy (Gemini 및 OpenAI 백엔드)
**claude-code-proxy**는 Claude Code로부터 Anthropic 형식의 요청을 받아 내부적으로 LiteLLM을 통해 OpenAI 또는 Gemini 형식으로 변환하는 Python 도구(3.3k GitHub 스타)입니다. Claude Code와 함께 Gemini 또는 GPT 모델을 specifically 사용하는 가장 간단한 방법입니다.
pip install claude-code-proxy
claude-code-proxy --port 8080
# Then point Claude Code at it
export ANTHROPIC_BASE_URL="http://localhost:8080"
export ANTHROPIC_API_KEY="your-gemini-or-openai-key"대규모 모노레포를 위해 Gemini의 100만 토큰 컨텍스트를 specifically 원한다면, 이것이 가장 직접적인 경로입니다.
LiteLLM (엔터프라이즈 범용 프록시)
LiteLLM은 부하 분산, 폴백 체인, 속도 제한 및 감사 로깅을 지원하며 100개 이상의 제공자를 지원하는 엔터프라이즈 등급 프록시입니다. 개인 개발자에게는 과잉 사양일 수 있지만, AI 모델 사용에 대한 거버넌스가 필요한 팀에게는 필수적입니다.
설정은 YAML config를 사용합니다:
model_list:
- model_name: claude-sonnet-4-20250514
litellm_params:
model: gemini/gemini-2.5-flash
api_key: os.environ/GEMINI_API_KEY
- model_name: claude-haiku-3-5-20241022
litellm_params:
model: deepseek/deepseek-chat
api_key: os.environ/DEEPSEEK_API_KEY# Start LiteLLM proxy
litellm --config config.yaml --port 4000
# Point Claude Code to LiteLLM
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-litellm"공식 Claude Code 문서의 중요한 주의 사항: "Anthropic은 LiteLLM을 승인, 유지 관리 또는 감사하지 않습니다." 사용해도 되지만, 이는 Anthropic 제품이 아닌 커뮤니티 도구임을 인지하세요. LiteLLM 튜토리얼에는 더 고급 구성 예제가 포함되어 있습니다.
판단: specifically Gemini나 OpenAI 모델을 원한다면 claude-code-proxy를 사용하세요. 팀에서 제공자 간 부하 분산, 폴백 및 감사 로깅이 필요하다면 LiteLLM을 사용하세요.
Claude Code Router vs LiteLLM: 어떤 것을 사용해야 할까?
Claude Code Router는 작업별 모델 라우팅을 원하는 개인 개발자에게 더 간단한 선택인 반면, LiteLLM은 부하 분산, 폴백 체인 및 감사 로깅이 필요한 팀을 위해 구축되었습니다. Router는 npm을 통해 설치되고 config.json을 읽는 반면, LiteLLM은 100개 이상의 제공자에 걸쳐 엔터프라이즈 YAML 구성 프록시를 실행합니다.
| 요소 | Claude Code Router | LiteLLM |
|---|---|---|
| 설정 난이도 | 중간: npm install, config.json 편집 | 고급: YAML config 파일 |
| 적합한 대상 | 작업별 라우팅을 원하는 개인 개발자 | 거버넌스가 필요한 팀 |
| 구성 형식 | config.json | YAML model_list |
| standout 기능 | 컨텍스트 인식 작업별 라우팅 | 부하 분산, 폴백, 감사 로깅 |
| 제공자 | OpenRouter, DeepSeek, Gemini, Ollama, Groq 등 | 제공자 간 100+ |
| 성숙도 | 30k+ GitHub 스타, Claude Code용으로 구축됨 | 엔터프라이즈 프록시, 커뮤니티 도구 (Anthropic 승인 없음) |
많은 설정 없이 DeepSeek으로 저렴한 배경 작업을 처리하고 Opus로 복잡한 추론을 수행하려는 개인 개발자라면 claude-code-router를 선택하세요. 팀에서 제공자 간 부하 분산, 속도 제한 및 감사 로그가 필요하다면 LiteLLM을 선택하세요.
다른 프록시들도 고려 중인가요? 최고의 LLM 게이트웨이 도구 roundup에서.side by side로 비교했습니다.
각 방법의 실제 비용은 얼마일까?
실제 숫자로 살펴봅시다. 가장 일반적인 모델/방법 조합에서 100만 토큰당 지불해야 하는 금액은 다음과 같습니다:
| 모델 / 방법 | 입력 (100만 토큰당) | 출력 (100만 토큰당) | 월간 추정치 (중간 사용량) |
|---|---|---|---|
| Claude Opus 4.6 (직접) | $5.00 | $25.00 | ~$50-150 |
| Claude Sonnet 4.6 (직접) | $3.00 | $15.00 | ~$30-60 |
| OpenRouter経由 Claude Sonnet | $3.00 | $15.00 | 동일 (비용 전가) |
| DeepSeek V3.2 (OpenRouter) | $0.27 | $1.10 | ~$3-8 |
| Gemini 2.5 Flash (OpenRouter) | $0.15 | $0.60 | ~$2-5 |
| Ollama (로컬) | 무료 | 무료 | $0 (하드웨어 비용 제외) |
가격 데이터는 Anthropic 공식 가격 페이지 및 OpenRouter에서 인용했습니다. 중간 사용량은 일일 코딩 세션 기준 월 ~5-10M 토큰을 가정합니다.
"Cost per 1M Output Tokens by Model"
데이터 테이블
| "Model" | "Output Cost" |
|---|---|
| "Opus 4.6" | 25 |
| "Sonnet 4.6" | 15 |
| "DeepSeek V3.2" | 1.1 |
| "Gemini 2.5 Flash" | 0.6 |
| "Ollama (local)" | 0 |
비용 격차는 상당하지만, 저렴한 모델은 특히 도구 호출 신뢰성이 중요한 복잡한 에이전트 작업에서 더 낮은 품질의 코드를 생성합니다. 백만 토큰당 출력 $1.10의 DeepSeek은 루틴 편집에 훌륭합니다. 그러나 Claude Code가 20개 파일에 걸쳐 읽고, 계획하고, 편집하고, 검증해야 하는 다중 파일 리팩토링의 경우? 여전히 Sonnet이나 Opus가 필요할 것입니다.
판단: 허용 가능한 품질로 비용을 절감하려면 OpenRouter + DeepSeek이 최고의 비율을 제공합니다. 제로 비용을 원한다면 하드웨어가 있을 경우 Ollama가 독보적입니다. 최대 품질을 원한다면 Anthropic 직접 사용이 여전히 왕입니다.
어떤 방법을 사용해야 할까?, 결정 프레임워크
다른 튜토리얼들이 건너뛰는 섹션입니다. "그냥 OpenRouter를 사용하세요"라고 말하는 대신, 실제 Needs에 맞춰 방법을 매칭해 보겠습니다:
| 필요한 것... | 이 방법 사용 | 이유 |
|---|---|---|
| 최대 모델 다양성, 단일 API 키 | OpenRouter | 300+ 모델, 쉬운 설정, 사용량 기반 과금 |
| 무료, 무제한, 코드 로컬 유지 | Ollama | 제로 비용, 완전한 프라이버시, 오프라인 가능 |
| 시각적 인터페이스가 있는 로컬 모델 | LM Studio | GUI 모델 브라우저, 쉬운 양자화 선택 |
| 스마트 작업별 라우팅 | claude-code-router | 추론은 Opus로, 빠른 편집은 DeepSeek으로 라우팅 |
| specifically Gemini 또는 OpenAI 모델 | claude-code-proxy | Anthropic 형식을 OpenAI/Gemini로 변환 |
| 엔터프라이즈: 부하 분산, 감사 | LiteLLM | 속도 제한, 폴백 체인, 팀 제어 |
정말로 전환해야 할까?
솔직한 견해: 복잡한 에이전트 코딩, 다중 파일 리팩토링, 아키텍처 계획, 까다로운 동시성 문제 디버깅을 수행하는 대부분의 개발자에게 직접 Anthropic을 통한 Claude Sonnet이 여전히 최고의 옵션입니다. 네이티브 Claude는 가장 신뢰할 수 있는 도구 호출, 자체 에이전트 워크플로우에 대한 최고의 이해, 그리고 프록시 지연 시간 제로를 제공합니다.
모델 전환은 특정 시나리오를 위한 최적화입니다:
- Sonnet 품질이 필요 없는 배경 작업으로 토큰을 소모하거나, Claude의 2x 사용량 제한에 자주 도달하는 경우
- 거대한 모노레포를 위해 Gemini의 100만 컨텍스트 윈도우가 필요한 경우
- 코드가 머신 외부로 나갈 수 없는 경우 (정부, 의료, 금융)
- 예산이 tight하고 완벽한 품질보다 허용 가능한 품질이 우선인 경우
위에 해당되지 않는다면, opusplan(Anthropic의 내장 라우팅)이면 충분할 수 있습니다.
여기서 가장 중요한 품질 지표는 도구 호출 신뢰성입니다. 계층 구조는 다음과 같습니다: 네이티브 Claude >> OpenRouter Claude >> DeepSeek/Gemini >> 로컬 모델. 아래로 내려갈수록 실패한 도구 호출, 환각된 파일 경로 및 불완전한 편집을 더 자주 보게 될 것입니다.
일반적인 문제 해결
"Model not found" 오류
가장 흔한 문제입니다. ANTHROPIC_BASE_URL을 설정했지만 세 가지 모델 슬롯을 모두 매핑하지 않았을 때 발생합니다. Claude Code는 프록시를 통해 Haiku나 Opus를 호출하려고 하지만, 프록시는 기본 Anthropic 모델 이름을 인식하지 못하여 오류가 발생합니다.
# Fix: set ALL three model slot variables
export ANTHROPIC_DEFAULT_HAIKU_MODEL="your-model"
export ANTHROPIC_DEFAULT_SONNET_MODEL="your-model"
export ANTHROPIC_DEFAULT_OPUS_MODEL="your-model"연결 거부 / 타임아웃
프록시가 실행 중이지 않거나, Claude Code가 잘못된 포트에 접속하고 있습니다. 프록시 프로세스가 활성 상태인지 확인하고 ANTHROPIC_BASE_URL의 포트를 다시 확인하세요. 방화벽과 VPN도 localhost 연결을 차단할 수 있습니다.
도구 호출 실패
모델이 Anthropic의 도구 사용 형식을 제대로 지원하지 않습니다. 증상: Claude Code가 멈춤, 빈 도구 호출 생성, 또는 잘못된 파일 편집. 검증된 도구 호출 지원을 갖춘 모델로 전환하세요. 로컬 모델 중에서는 Qwen 2.5 Coder와 devstral이 이를 가장 잘 처리합니다.
스트리밍 문제
일부 프록시는 서버 전송 이벤트(server-sent events)를 올바르게 처리하지 않습니다. 응답이 스트리밍되지 않고 한꺼번에 나타나거나, 응답 중간에 끊깁니다. 프록시 버전이 최신인지 확인하고 GitHub 이슈에서 알려진 스트리밍 버그를 확인하세요.
컨텍스트 윈도우 초과
로컬 모델은 종종 4K-8K 컨텍스트 윈도우를 기본값으로 사용합니다. 실제 코딩 세션을 위해 Claude Code는 그보다 훨씬 더 많은 것이 필요합니다. 32K+ 컨텍스트를 가진 모델을 사용하거나, OpenRouter를 통해 Gemini(100만 윈도우)로 긴 컨텍스트 작업을 라우팅하세요.
OpenRouter를 위해 먼저 로그아웃해야 함
직접 Anthropic에서 OpenRouter로 전환하는 경우, 먼저 claude /logout을 실행하세요. Claude Code는 인증을 캐시하므로 기본 URL을 변경한 후에도 Anthropic 키를 계속 사용하려고 시도합니다.
# Clear cached authentication before switching providers
claude /logoutFAQ
Claude Code를 GPT-4 또는 Gemini와 함께 사용할 수 있나요?
예. claude-code-proxy는 Anthropic 형식 요청을 OpenAI 또는 Gemini 형식으로 변환합니다. 또한 단일 API 키로 OpenRouter를 통해 둘 다 접근할 수 있습니다. 도구 호출은 네이티브 Claude보다 신뢰성이 떨어질 수 있으며, 특히 복잡한 다단계 작업에서 그렇습니다.
Anthropic API 키 없이 Claude Code를 어떻게 사용하나요?
완전히 무료인 로컬 사용을 위해 Ollama를 사용하세요. 어떤 제공자의 API 키도 필요하지 않습니다. 또는 OpenRouter의 API 키 형식을 사용하세요. 여전히 ANTHROPIC_API_KEY 환경 변수를 설정하지만, 이는 프록시의 키를 가리킵니다 (예: OpenRouter의 경우 sk-or-v1-..., Ollama의 경우 "ollama").
Ollama로 Claude Code를 설정하는 방법은?
Ollama를 설치하고, qwen2.5-coder:14b와 같은 모델을 풀하고, ollama launch claude를 실행한 다음, 세 가지 환경 변수(ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY 및 세 가지 모델 슬롯 변수)를 설정하세요. 완전한 코드는 위의 Ollama 섹션을 참조하세요.
Claude Code와 가장 잘 작동하는 모델은 무엇인가요?
클라우드용: Claude Sonnet 4가 최고의 코딩 품질을 제공하며, DeepSeek V3.2가 최고의 가성비입니다. 로컬용: Qwen 2.5 Coder 14B가 현재 금표준(gold standard)입니다. 결정적 요인은 도구 호출 신뢰성인데, Claude Code는 파일 작업을 위해 이에 크게 의존하며 네이티브 Claude 모델이 이를 가장 잘 처리합니다.
Claude Code의 "model not found" 오류를 어떻게 수정하나요?
세 가지 모델 슬롯 환경 변수를 모두 설정하세요: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL. 이 오류는 Claude Code가 세 개의 내부 모델 슬롯을 사용하고, 매핑되지 않은 슬롯이 프록시가 인식하지 못하는 모델 이름을 호출하려고 하기 때문에 발생합니다.
Claude Code가 로컬 모델로 오프라인에서 작동할 수 있나요?
예. Ollama와 LM Studio 모두 인터넷 연결 없이 머신에서 완전히 모델을 실행합니다. 코드는 하드웨어 외부로 유출되지 않습니다. 적절한 사양이 필요합니다 -- 7B 모델에는 최소 16GB RAM, 더 큰 모델에는 32GB+ RAM.
LM Studio를 Claude Code와 함께 사용할 수 있나요?
예. LM Studio는 ANTHROPIC_BASE_URL을 http://localhost:1234/v1로, ANTHROPIC_API_KEY를 lm-studio로 설정하여 Claude Code가 연결하는 로컬 서버를 실행합니다. Qwen 2.5 Coder와 같은 코딩 모델을 다운로드하고, LM Studio의 GUI에서 서버를 시작한 다음, 모델 슬롯을 매핑하세요. 이는 Ollama의 CLI에 대한 시각적 대안입니다.
ANTHROPIC_BASE_URL은 무엇이며 어떻게 사용하나요?
이는 Claude Code에게 API 요청을 보낼 위치를 알려주는 환경 변수입니다. 기본적으로 https://api.anthropic.com을 가리킵니다. 이를 Anthropic 호환 엔드포인트, OpenRouter(https://openrouter.ai/api), Ollama(http://localhost:11434), LiteLLM(http://localhost:4000) 등으로 변경하세요.
claude-code-router가 LiteLLM보다 나은가요?
서로 다른 문제를 위한 서로 다른 도구입니다. claude-code-router는 더 간단하며(npm install, config.json 편집, 완료), specifically Claude Code용으로 설계되었습니다. LiteLLM은 부하 분산, 속도 제한, 폴백 체인 및 감사 로깅을 갖춘 엔터프라이즈 등급입니다. 개인 개발자라면 claude-code-router를 사용하세요. 거버넌스 Needs가 있는 팀이라면 LiteLLM을 사용하세요.
비-Anthropic 모델을 사용하면 얼마나 절약할 수 있나요?
Claude Opus 4.6에서 DeepSeek V3.2로 전환하면 출력 토큰 비용이 약 95% 절감됩니다 (백만 토큰당 $25 대 $1.10). 하드웨어가 있다면 Ollama는 이를 제로로 만듭니다. 하지만 품질 trade-off는 현실적입니다. 복잡한 다단계 에이전트 작업에서 정확도 저하, 덜 신뢰할 수 있는 도구 호출, 그리고 더 많은 환각된 파일 경로를 예상하세요.
도구 호출이 모든 프록시 방법에서 작동하나요?
전반적으로 신뢰할 수 있게 작동하지는 않습니다. 네이티브 Claude가 최고의 도구 호출 지원을 제공합니다. Claude 모델과 함께하는 OpenRouter는 거의 마찬가지로 잘 작동합니다. DeepSeek과 Gemini는 부분적인 지원을 제공하며, 간단한 도구 호출은 작동하지만 복잡한 체인은 실패할 수 있습니다. Ollama를 통한 로컬 모델은 도구 호출 신뢰성이 가장 낮습니다. 이는 Anthropic에서 전환할 때 가장 중요한 품질 우려 사항입니다.