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 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 모델에는 제약이 있습니다. 주요 내용을 정리합니다.

RPM은 OpenRouter의 상황에 따라 변동됩니다. 공식 사이트인 openrouter.ai/models에서 최신 값을 확인하십시오.

Claude Code는 기본적으로 재시도 간격이 짧습니다. 다음 설정으로 완화할 수 있습니다.

// .claude/settings.json
{
"model": "deepseek/deepseek-chat-v3-0324:free",
...
}

또한, 작업 세션을 한 번에 하나의 태스크씩 순차적으로 실행하여 (병렬 실행하지 않음) RPM 초과를 방지할 수 있습니다.

:free 모델은 컨텍스트 상한이 유료 버전보다 낮을 수 있습니다. 대규모 리포지토리에서 claude를 사용할 때는 /compact 명령어를 조기에 실행하여 컨텍스트를 압축해 두십시오.

# Claude Code 내에서의 명령어
/compact

OpenRouter에는 Route 기능이 있습니다. :free 모델이 429 에러를 반환할 때, 동일한 이름의 유료 모델로 자동 폴백 (Fallback) 시키는 설정이 가능합니다.

ANTHROPIC_BASE_URL의 쿼리 파라미터는 사용할 수 없지만, 모델명에서 :free를 제거하는 것만으로 유료 플랜으로 전환됩니다.

스크립트로 전환하는 경우에는 다음과 같은 래퍼 (Wrapper)를 사용할 수 있습니다:

#!/bin/bash
# claude-free.sh: 무료 모델로 시작, 실패 시 유료 모델로 재시도
MODEL_FREE="deepseek/deepseek-chat-v3-0324:free"
...

OpenRouter의 모델명은 /로 구분된 완전 수식 이름 (Fully Qualified Name)이 필요합니다. deepseek-r1이 아니라 deepseek/deepseek-r1:free라고 지정해야 합니다.

# NG
claude --model deepseek-r1:free
# OK
...

R1 등과 같은 사고 모델 (Reasoning Model)은 CoT가 길어 첫 응답까지 60초 이상 걸릴 수 있습니다. apiTimeoutMs: 180000 (3분)을 설정해 두면 안정적입니다.

일부 :free 모델은 도구 호출 (Tool Use)을 지원하지 않습니다. Claude Code는 파일 읽기/쓰기 등을 위해 내부 도구를 사용하므로, 반드시 tool use 대응 모델을 선택해야 합니다.

대응 여부는 OpenRouter의 각 모델 페이지 (Features 항목)에서 Tools가 ✅로 표시된 것을 선택하십시오.

Claude Code의 UX는 그대로 유지하면서 추론 비용을 거의 제로로 억제할 수 있습니다. 일상적인 코딩 지원이나 CI 상의 자동 리뷰 등, 비용 민감도가 높은 유스케이스부터 시도해 보시는 것을 추천합니다.

• Claude Code 공식 문서 — Model Configuration
• OpenRouter — 모델 목록
• OpenRouter — API Reference
• DeepSeek R1 기술 보고서 (arXiv:2501.12948)
• Qwen3 기술 블로그

✍️ 본 기사 저자: Godo Kaisha Jimolab (合同会社ジモラボ)

Jimolab은 하치오지를 거점으로 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 또한 그러한 개발 과정의 부산물입니다.

• 🌐 공식 사이트: https://locallab.jp
• 🔍 AI SEO 최적화 SaaS: lookupai.jp
• 📺 YouTube: @locallab_llc
• ✉️ 문의하기: info@locallab.jp

관심이 생기셨다면, 꼭 각 SNS 팔로우도 부탁드립니다!