- Claude Code의
ANTHROPIC_API_KEY
을 교체하는 것만으로 OpenRouter를 경유한 무료 모델 사용 가능 -
claude --model
플래그로 Qwen3, Gemini Flash, Llama4 등에 즉시 전환 가능 - 무료 할당량의 레이트 제한을 회피하는 3가지 로테이션 전략 소개
- 월간 비용:
$0(무료 모델만 사용 시)
AI 코딩 어시스턴트의 비용은 개인 개발자나 소규모 팀에게 무시할 수 없는 비용이 되어가고 있다. Claude Code는 강력하지만, claude.ai Pro 구독($20/월~) + API 종량제 과금이 발생하는 구성이 일반적이다.
그런데 OpenRouter에는 google/gemini-flash-1.5-8b:free
이나 qwen/qwen3-235b-a22b:free
처럼 :free 접미사가 붙은 무료 모델이 다수 존재한다. Claude Code는 커스텀 엔드포인트를 설정할 수 있기 때문에, 이를 조합하면
제로 코스트의 AI 개발 환경을 구현할 수 있다.
본 기사에서는 실제 설정 절차, 모델 선정 지침, 레이트 제한 대처법을 설명한다.
| 항목 | 버전 / 조건 |
|---|
| Claude Code | v1.x (npm: @anthropic-ai/claude-code) |
| ... | |
| OpenRouter는 OpenAI 호환 API로 작동하는 프록시 서비스이다. 엔드포인트는 다음과 같다: | |
Base URL: https://openrouter.ai/api/v1
인증: Authorization: Bearer sk-or-v1-xxxx
모델: provider/model-name:variant
무료 모델에는 :free 접미사가 붙는다. 2026년 5월 기준으로 주요 무료 모델은 다음과 같다:
| 모델 ID | 특징 | 컨텍스트 |
|---|---|
google/gemini-flash-1.5-8b:free | 고속・경량・코드 보완용 | 1M tokens |
google/gemini-2.0-flash-exp:free | Gemini 2.0 계열・멀티모달 | 1M tokens |
qwen/qwen3-235b-a22b:free | 초거대・코드 생성 고정밀도 | 128K tokens |
meta-llama/llama-4-scout:free | Meta 최신・지시 추종성 높음 | 512K tokens |
mistralai/mistral-small-3.1-24b-instruct:free | Mistral 경량・저지연 | 128K tokens |
주의: 무료 모델은 이용 가능 상황이 변동하므로, https://openrouter.ai/models?order=newest&supported_parameters=free
에서 최신 목록을 확인하는 것이 좋다.
Claude Code는 환경변수를 통해 Anthropic API의 목적지를 변경할 수 있다.
# ~/.bashrc or ~/.zshrc
# OpenRouter API 키 (openrouter.ai에서 발급)
export ANTHROPIC_API_KEY="sk-or-v1-<YOUR_OPENROUTER_KEY>"
...
claude --model "google/gemini-flash-1.5-8b:free" "Hello, what model are you?"
정상적으로 응답이 돌아오면 설정 완료이다.
여러 프로젝트에서 모델을 구분하여 사용하고 싶다면 direnv가 편리하다:
# 프로젝트 루트에 .envrc를 생성
cat > .envrc << 'EOF'
export ANTHROPIC_API_KEY="sk-or-v1-<YOUR_OPENROUTER_KEY>"
...
무료 모델에는 제약이 있다. 현실적인 운영을 위해 파악해 두자.
무료 모델은 대부분 20 RPM (Requests Per Minute)・200 RPD (Requests Per Day) 정도의 제한이 있다.
대처법: 지수 백오프(Exponential Backoff)를 포함한 셸 wrapper
#!/bin/bash
# claude-free.sh: 속도 제한에 걸리면 자동 재시도
MAX_RETRIES=5
...
chmod +x claude-free.sh
alias claude="~/scripts/claude-free.sh"
Qwen3-235b는 128K 토큰이지만, 대규모 코드베이스에서는 부족할 수 있습니다.
대처 방안: .claudeignore로 컨텍스트 축소
# .claudeignore
node_modules/
dist/
...
프로젝트 루트에 놓기만 하면, Claude Code가 자동으로 제외해 줍니다.
무료 모델은 시간대에 따라 프로바이더가 혼잡하여 타임아웃이 증가합니다.
대처 방안: 모델 로테이션 스크립트
#!/bin/bash
# rotate-model.sh: 실패하면 다음 무료 모델을 시도
MODELS=(
...
모든 무료 모델이 만능은 아닙니다. 용도에 따라 사용하면 품질이 향상됩니다.
Gemini Flash 8B: 응답 속도가 빠르고, sed / awk 수준의 짧은 코드 수정에 적합합니다. Claude Code에서 가장 자주 호출되는 'diff 생성' 작업에 유용합니다.
export CLAUDE_MODEL="google/gemini-flash-1.5-8b:free"
claude "이 파일의 console.log를 전부 삭제해"
Qwen3-235B: 대규모 모델로 추론 품질이 높습니다. '이 코드를 어떻게 재설계할지', '이 알고리즘의 시간 복잡도는'과 같이 사고가 필요한 작업에 유용합니다.
export CLAUDE_MODEL="qwen/qwen3-235b-a22b:free"
claude "이 React 컴포넌트를 atomic design에 따라 분할하는 설계안을 내줘"
Llama4: 512K 토큰의 긴 컨텍스트를 활용할 수 있습니다. 리포지토리 전체를 읽게 하여 '전체 최적화 리팩토링 안'을 도출시키는 용도에 적합합니다.
export CLAUDE_MODEL="meta-llama/llama-4-scout:free"
claude "src/ 이하를 전부 읽고 의존성 문제점을 나열해줘"
프로젝트 루트에 CLAUDE.md를 두면, Claude Code가 세션 시작 시 읽어들입니다. 여기에 모델 선정 지침을 작성해 두면, AI 스스로 적절한 모델을 선택하는 데 도움이 됩니다.
# Project: my-app
## AI 개발 규칙
- 경미한 편집/포맷 수정: Gemini Flash 8B를 권장
...
| 구성 | 월 예상 비용 |
|---|
| Claude Pro + API 종량 | $20~$80 |
| OpenAI GPT-4o 종량 (중규모 이용) | $15~$50 |
| OpenRouter 무료 모델만 | $0 |
| OpenRouter 무료 + 유료 모델 혼재 | $1~$10 (중요 작업에만 과금) |
ANTHROPIC_BASE_URL을 https://openrouter.ai/api/v1로 설정하는 것만으로 Claude Code가 OpenRouter를 통해 작동합니다 - :free 접미사가 붙은 모델로 월 0원의 AI 개발 환경이 실현됩니다 - 속도 제한에는 지수 백오프(exponential backoff) wrapper + 모델 로테이션으로 대응합니다.
- 용도별로 Gemini Flash (속도) / Qwen3-235B (품질) / Llama4 (장문)를 사용합니다.
- 실제 사용이나 중요한 판단에만 유료 모델로 폴백(fallback)합니다.
하이브리드 전략이 현실적인 해결책입니다.
무료 모델의 품질은 2026년 기준으로 실용 수준에 도달했으며, 보일러플레이트 생성, 테스트 추가, 소규모 리팩토링 등에서는 유료 모델과 비교할 수 없습니다. 일단 설정하는 데 10분만 투자하여 시도해 보시길 바랍니다.
✍️ 본 기고지 작성자: 주식회사 지모랩
지모랩은 하치오지에 거점을 두고 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기고지의 기술 검증 역시 그러한 개발 과정의 부산물입니다.
내용이 유용하거나 흥미로웠다면, 저희의 다양한 소셜 미디어(SNS) 채널도 팔로우 부탁드립니다!
