Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Claude Code의 baseURL 설정을 활용하여 OpenRouter의 무료 모델을 연결함으로써 API 비용을 절감하는 방법을 소개합니다. 작업의 중요도에 따라 유료 모델과 무료 모델을 혼합 사용하는 이층 운용 전략을 제안합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기:free 접미사 모델은 상용 이용이 가능하면서도 무료로 사용할 수 있는 것이 많다. Claude Code는 ANTHROPIC_API_KEY 외에 OPENROUTER_API_KEY + baseURL 설정을 통해 임의의 모델로 연결할 수 있다. 모델 품질·속도 제한(Rate Limit)·컨텍스트 길이(Context Length)의 삼각형을 의식하여 모델을 선택하면 비용 효율을 극대화할 수 있다.Claude Code나 Cursor를 본격적으로 사용하기 시작하면, 월말의 API 청구 금액에 놀랄 때가 있다. 특히 반복적인 작업(테스트 생성·리팩터링·문서 보완)은 대량의 토큰을 소비하는 것에 비해 요구되는 품질 수준이 비교적 낮다.
OpenRouter는 다수의 LLM을 단일 API 엔드포인트로 제공하는 프록시(Proxy) 서비스다. 2024년 말부터 2025년에 걸쳐 Qwen·DeepSeek·Mistral 계열의 고품질 모델들이 :free 엔드포인트를 제공하기 시작했으며, 실용적인 수준에 도달했다.
이를 Claude Code와 조합하면 "가벼운 작업은 제로 코스트(Zero Cost), 무거운 작업만 Claude API 사용"이라는 이층 운용을 실현할 수 있다.
OpenRouter의 모델 ID에는 다음과 같은 2가지 패턴이 있다:
qwen/qwen3-8b # 유료 (토큰 과금)
qwen/qwen3-8b:free # 무료 범위 (속도 제한 있음)
2025년 시점의 대표적인 :free 모델:
| 모델 ID | 컨텍스트 길이 | 특징 |
|---|---|---|
qwen/qwen3-8b:free | 32k | 일본어 대응·경량 고속 |
qwen/qwen3-14b:free | 32k | 일본어 강점·추론 안정 |
deepseek/deepseek-chat:free | 64k | 코드 생성 특화 |
mistralai/mistral-7b-instruct:free | 32k | 경량·영어 코드 적합 |
microsoft/phi-3-mini-128k-instruct:free | 128k | 초장기 컨텍스트 |
google/gemma-3-9b-it:free | 8k | 범용·안정 |
⚠️ :free 모델은 속도 제한(RPM / TPM)이 유료 범위보다 엄격하여, 혼잡 시 429 에러가 증가한다. 중요한 동기 처리에는 사용하지 말 것.
Claude Code는 내부적으로 Anthropic SDK의 baseURL을 교체함으로써 다른 프로바이더(Provider)에 접속할 수 있다.
# .env.local (git ignore 권장)
ANTHROPIC_API_KEY=sk-ant-XXXXXXXX # Anthropic 본사
OPENROUTER_API_KEY=sk-or-XXXXXXXX # OpenRouter
...
Claude Code (claude CLI)는 ANTHROPIC_BASE_URL 환경 변수를 참조한다.
# OpenRouter를 향해 실행
ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1 \
ANTHROPIC_API_KEY=$OPENROUTER_API_KEY \
...
{
"env": {
"ANTHROPIC_BASE_URL": "https://openrouter.ai/api/v1",
...
⚠️ settings.json에 API 키를 직접 작성하는 경우, 파일 권한을 600으로 설정한다 (chmod 600 ~/.claude/settings.json).
# ~/.zshrc or ~/.bashrc
alias claude-free='ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1 \
ANTHROPIC_API_KEY=$OPENROUTER_API_KEY claude --model qwen/qwen3-14b:free'
...
일상 작업은 claude-free, 설계 판단·복잡한 디버깅은 claude-pro로 구분하여 사용한다.
Claude Code를 거치지 않고, 스크립트 내에서 OpenRouter를 호출하는 경우의 최소 구현 예시.
// openrouter-client.mjs
const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
async function chat(model, messages) {
...
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
...
무료 모델을 선택할 때는 **품질(Quality)・속도(Speed)・컨텍스트 길이(Context Length)・레이트 리밋(Rate Limit)**의 4가지 축으로 평가한다.
| 작업 | 추천 모델 | 이유 |
|---|---|---|
| 코멘트・docstring 생성 | qwen/qwen3-8b:free | 속도 중시・경량 |
| 유닛 테스트 생성 | deepseek/deepseek-chat:free | 코드 정확도 높음 |
| 대용량 파일 리팩토링 | microsoft/phi-3-mini-128k-instruct:free | 128k 컨텍스트 |
| 일본어 PR 설명문 생성 | qwen/qwen3-14b:free | 일본어 품질 |
| 설계 리뷰・중요 판단 | claude-sonnet-4-5 (유료) | 정확도 최우선 |
:free 모델은 통상적으로 20 RPM / 200k TPD 정도의 제한이 있다. 자동화 스크립트에서는 지수 백오프 (Exponential Backoff)를 구현한다:
async function chatWithRetry(model, messages, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
try {
...
개발 작업
│
├─ 경량 작업 (테스트 보완・코멘트・타입 수정)
...
OpenRouter의 대시보드에는 Usage 페이지가 있어, 모델별・일별 토큰 소비량을 확인할 수 있다. 우선 1주일간의 사용량을 모니터링하여 "어떤 작업에 얼마나 소비하고 있는지"를 파악하는 것이 첫 번째 단계이다.
| 포인트 | 상세 |
|---|---|
① OpenRouter :free의 실력 | 2025년 현재, Qwen3/DeepSeek 계열은 실용적인 수준에 도달했다 |
| ② Claude Code와의 연결 | ANTHROPIC_BASE_URL + ANTHROPIC_API_KEY 교체만으로 작동한다 |
| ③ 이중 운용 | 경량 작업 = 무료, 중요 작업 = 유료로 설정하여 비용 효율을 극대화한다 |
| ④ 레이트 리밋(Rate Limit) 대책 | 지수 백오프 (Exponential Backoff)를 구현해 두면 자동화 시에도 안정적으로 가동된다 |
| ⑤ 모델 선정 | 작업의 특성 (코드/일본어/긴 컨텍스트)에 맞춰 선택한다 |
OpenRouter의 :free 할당량은 연구・개인 개발・자동화 보조 도구로서 매우 뛰어나다. 실제 서비스의 크리티컬 패스 (Critical Path)에는 유료 모델을 사용하면서, 반복 작업의 비용을 절감하는 전략은 앞으로 더욱 중요해질 것이다.
✍️ 본 기사 저자: 합동회사 지모라보 (Jimolabo LLC)
지모라보는 하치오지를 거점으로 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증도 그러한 개발 과정의 부산물입니다.
관심이 생기셨다면, 꼭 각 SNS 팔로우도 부탁드립니다!
| 체크 항목 | 결과 |
|---|---|
| 4-A~4-D에 해당하는 기술은 없는가? | ✅ YES (사내 구성・saas-template・하네스 구성은 일절 포함되지 않음) |
| ... | |
| 판정: 모든 항목 YES → 공개 가능 |