Claude Code의 ANTHROPIC_API_KEY를 교체하는 것만으로 OpenRouter를 통한 무료 모델을 사용할 수 있습니다.
deepseek/deepseek-r1:free나 google/gemma-3-27b-it:free와 같은 고품질 모델을 월 $0로 이용 가능합니다. 무료 범위의 RPM/TPM 제한을 .claude/settings.json의 타임아웃 설정으로 흡수하는 요령을 해설합니다.
Claude Code는 강력한 코딩 에이전트(Coding Agent)이지만, Anthropic API를 직접 사용하면 **Sonnet 3.7 기준으로 1 MTok당 $3 (입력)**의 비용이 발생합니다. 어느 정도 규모의 태스크를 수행하면 하루에 몇 달러가 순식간에 사라집니다.
반면, OpenRouter는 OpenAI 호환 API로서 다수의 모델을 라우팅(Routing)하고 있으며, :free 접미사가 붙은 모델은 레이트 리미트(Rate Limit) 내라면 과금 없이 사용할 수 있습니다.
이 두 가지를 조합하면 "Claude Code의 UX + 무료 모델의 추론"을 실현할 수 있습니다. 본 기사에서는 그 구체적인 설정 절차와 주의점을 정리합니다.
| 항목 | 내용 |
|---|
| Claude Code 버전 | @anthropic-ai/claude-code ≥ 0.2 (2025년 후반~서) |
OpenRouter :free 모델 | 동일 모델에 :free 태그가 붙은 변형(Variant). RPM 20~60 정도 · 컨텍스트(Context) 제한 있음 |
| OpenAI 호환성 | OpenRouter는 https://openrouter.ai/api/v1에서 OpenAI Chat Completions 사양을 준수 |
Claude Code는 내부적으로 Anthropic SDK를 호출하지만, 다음 환경 변수를 덮어쓰면 **OpenAI 호환 엔드포인트(Endpoint)**로 전환됩니다.
# ~/.zshrc or ~/.bashrc に追記
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxx" # OpenRouter의 키
주의: ANTHROPIC_API_KEY라는 변수명 그대로 OpenRouter의 키를 넣습니다. Claude Code가 참조하는 것은 어디까지나 ANTHROPIC_API_KEY이며, 값이 OpenRouter 키라 하더라도 동작합니다.
설정 후 새로운 셸(Shell)을 열거나 source ~/.zshrc를 실행하여 반영합니다.
Claude Code의 실행 시 옵션 --model로 모델을 지정합니다.
# DeepSeek R1 무료 범위 (추론 특화 · 128K context)
claude --model deepseek/deepseek-r1:free
# Google Gemma 3 27B (밸런스형 · 고품질)
...
또는 .claude/settings.json (프로젝트 단위)에 고정할 수도 있습니다.
{
"model": "google/gemma-3-27b-it:free",
"apiTimeoutMs": 120000
...
}
apiTimeoutMs를 길게 설정하는 이유는 단계 3에서 설명합니다.
:free 모델에는 제약이 있습니다. 주요 내용을 정리합니다.
| 모델 | Context | RPM | 특징 |
|---|
deepseek/deepseek-r1:free | 128K | ~20 | 추론 강함 · CoT 김 |
deepseek/deepseek-chat-v3-0324:free | 128K | ~60 | 코딩 적합 · 빠름 |
google/gemma-3-27b-it:free | 96K | ~30 | 다국어 · 밸런스형 |
meta-llama/llama-3.3-70b-instruct:free | 131K | ~20 | 범용 · 영어 강함 |
qwen/qwen3-14b:free | 40K | ~30 | 일본어 · 코드 양립 |
RPM은 OpenRouter의 상황에 따라 변동됩니다. 공식 사이트인 openrouter.ai/models에서 최신 값을 확인하십시오.
Claude Code는 기본적으로 재시도 간격이 짧습니다. 다음 설정으로 완화할 수 있습니다.
// .claude/settings.json
{
"model": "deepseek/deepseek-chat-v3-0324:free",
...
}
또한, 작업 세션을 한 번에 하나의 태스크씩 순차적으로 실행하여 (병렬 실행하지 않음) RPM 초과를 방지할 수 있습니다.
:free 모델은 컨텍스트 상한이 유료 버전보다 낮을 수 있습니다. 대규모 리포지토리에서 claude를 사용할 때는 /compact 명령어를 조기에 실행하여 컨텍스트를 압축해 두십시오.
# Claude Code 내에서의 명령어
/compact
| 시나리오 | 권장 모델 | 이유 |
|---|
| 버그 수정 · 소규모 리팩토링 | deepseek/deepseek-chat-v3-0324:free | RPM이 높고 응답이 빠름 |
| 설계 리뷰 · 복잡한 추론 | deepseek/deepseek-r1:free | CoT (Chain of Thought)가 강력함 |
| 일본어 주석 · 문서 생성 | qwen/qwen3-14b:free | 일본어 품질이 높음 |
| 영어 중심 · 대규모 코드베이스 | meta-llama/llama-3.3-70b-instruct:free | 131K context |
OpenRouter에는 Route 기능이 있습니다. :free 모델이 429 에러를 반환할 때, 동일한 이름의 유료 모델로 자동 폴백 (Fallback) 시키는 설정이 가능합니다.
ANTHROPIC_BASE_URL의 쿼리 파라미터는 사용할 수 없지만, 모델명에서 :free를 제거하는 것만으로 유료 플랜으로 전환됩니다.
스크립트로 전환하는 경우에는 다음과 같은 래퍼 (Wrapper)를 사용할 수 있습니다:
#!/bin/bash
MODEL_FREE="deepseek/deepseek-chat-v3-0324:free"
...
OpenRouter의 모델명은 /로 구분된 완전 수식 이름 (Fully Qualified Name)이 필요합니다. deepseek-r1이 아니라 deepseek/deepseek-r1:free라고 지정해야 합니다.
claude --model deepseek-r1:free
...
R1 등과 같은 사고 모델 (Reasoning Model)은 CoT가 길어 첫 응답까지 60초 이상 걸릴 수 있습니다. apiTimeoutMs: 180000 (3분)을 설정해 두면 안정적입니다.
일부 :free 모델은 도구 호출 (Tool Use)을 지원하지 않습니다. Claude Code는 파일 읽기/쓰기 등을 위해 내부 도구를 사용하므로, 반드시 tool use 대응 모델을 선택해야 합니다.
대응 여부는 OpenRouter의 각 모델 페이지 (Features 항목)에서 Tools가 ✅로 표시된 것을 선택하십시오.
| 포인트 | 내용 |
|---|
| 환경 변수 2개 | ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY를 교체하기만 하면 됨 |
| 비용 | :free 모델이라면 $0 (RPM 제한 내) |
| 품질 | DeepSeek V3 / R1은 유료 모델과 대등한 수준 |
| 주의 사항 | RPM 제한 · tool use 대응 확인 · 타임아웃 설정 필요 |
Claude Code의 UX는 그대로 유지하면서 추론 비용을 거의 제로로 억제할 수 있습니다. 일상적인 코딩 지원이나 CI 상의 자동 리뷰 등, 비용 민감도가 높은 유스케이스부터 시도해 보시는 것을 추천합니다.
- Claude Code 공식 문서 — Model Configuration
- OpenRouter — 모델 목록
- OpenRouter — API Reference
- DeepSeek R1 기술 보고서 (arXiv:2501.12948)
- Qwen3 기술 블로그
✍️ 본 기사 저자: Godo Kaisha Jimolab (合同会社ジモラボ)
Jimolab은 하치오지를 거점으로 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 또한 그러한 개발 과정의 부산물입니다.
관심이 생기셨다면, 꼭 각 SNS 팔로우도 부탁드립니다!
