상업적 이용 가능하며 속도 제한이 있는 완전 무료 모델입니다.
ANTHROPIC_API_KEY를 교체하기만 하면 Claude Code의 백엔드를 전환할 수 있습니다. Qwen3 / Gemini 2.0 Flash / Llama 4 등, 2026년 기준으로 유력한 모델들이 준비되어 있습니다.- 비용이 전혀 들지 않으면서 'AI 페어 프로그래밍'을 시도할 수 있는 가장 빠른 경로를 소개합니다.
Claude Code(구 claude-code CLI)는 Anthropic의 공식 CLI로, 터미널에서 Claude와 직접 대화하며 코딩을 진행할 수 있는 도구입니다.
하지만 Anthropic의 종량제 과금 때문에 도입을 망설이는 엔지니어들도 많습니다.
OpenRouter는 다양한 LLM 프로바이더를 위한 **통합 API 게이트웨이(unified API gateway)**이며, model_name:free 형식으로 모델을 지정하면 속도 제한 범위 내에서 무료로 이용할 수 있습니다.
Claude Code는 내부적으로 OpenAI 호환 API를 사용하기 때문에, OpenRouter를 중계하면 Anthropic의 API 키 없이 구동할 수 있습니다. 본 기사에서는 그 절차를 5단계로 설명합니다.
주의: OpenRouter의 :free 티어는 속도 제한이 엄격하여(분당 수십 리퀘스트 정도), 실제 자동화에는 적합하지 않습니다. 개인 학습 및 프로토타이핑 용도를 전제로 합니다.
| 항목 | 버전 / 비고 |
|---|
| OS | macOS 14 / Ubuntu 22.04 LTS |
| ... | |
npm install -g @anthropic-ai/claude-code
설치 후, 버전 확인:
claude --version
# claude-code/x.x.x
- openrouter.ai에 접속하여 GitHub 또는 Google 계정으로 가입합니다.
- 대시보드 → Keys → Create Key를 클릭합니다. - 키 이름(예:
claude-code-dev)을 입력하고 생성합니다. - 표시된 sk-or-v1-xxxx...를 복사하여 메모장 등에 저장합니다.
무료 사용량 확인 방법:
Models 페이지에서 Free 배지가 있는 모델을 선택합니다. 2026년 기준으로 :free 지원 주요 모델은 다음과 같습니다:
| 모델 | 특징 |
|---|
qwen/qwen3-8b:free | 경량・고속・코드 생성에 능함 |
google/gemini-2.0-flash-exp:free | Google 제작・멀티모달 대응 |
meta-llama/llama-4-scout:free | Meta 제작・긴 컨텍스트 |
mistralai/mistral-7b-instruct:free | 유럽산・안정적인 출력 |
:free 모델의 최신 목록은 https://openrouter.ai/models?q=free에서 확인할 수 있습니다. 라인업은 수시로 변경됩니다.
Claude Code는 ANTHROPIC_BASE_URL과 ANTHROPIC_API_KEY를 참조합니다. OpenRouter를 사용하도록 지정하려면 다음을 설정합니다.
# ~/.bashrc 또는 ~/.zshrc에 추가
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="sk-or-v1-여기에OpenRouter의키"
set -Ux ANTHROPIC_BASE_URL "https://openrouter.ai/api/v1"
set -Ux ANTHROPIC_API_KEY "sk-or-v1-여기에OpenRouter의키"
프로젝트 루트에 .envrc를 생성합니다:
export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="sk-or-v1-여기에OpenRouter의키"
이로써 cd
이전 청크와 일관된 용어 및 톤을 유지하며 번역합니다.
OpenRouter로 전환되는 시점에만 모델을 변경할 수 있습니다. Anthropic의 원본(네이티브) 프로젝트를 사용하는 경우에도 관리가 쉬워집니다.
Claude Code에서 모델을 지정하는 방법은 두 가지가 있습니다.
claude --model "qwen/qwen3-8b:free"
프로젝트 루트에 claude.json (또는 .claude/settings.json)을 배치합니다:
{
"model": "qwen/qwen3-8b:free"
}
이렇게 하면 claude 명령어만으로 자동으로 지정된 모델로 실행됩니다.
정상적으로 응답이 돌아오면 설정 완료입니다.
# 기존 파일을 전달하여 리뷰 요청
claude "이 파일의 코드를 리뷰하고 개선점을 알려줘" < src/utils.ts
cat src/calculator.ts | claude "이 코드에 대한 Jest 테스트를 작성해줘"
claude "src/api/handler.ts을 읽고, 에러 핸들링을 개선하는 리팩토링 안을 내줘"
git diff --staged | claude "이 diff에 대한 Conventional Commits 형식의 커밋 메시지를 작성해줘"
:free 모델은 429 Too Many Requests 에러가 자주 발생합니다. 이에 대한 3가지 대처 방안을 제시합니다.
retry_claude() {
local max=5
local delay=2
...
}
OpenRouter의 API는 models 배열을 받을 수 있지만, Claude Code CLI를 통해서는 직접 지정할 수 없습니다. 대신 모델 이름을 셸 스크립트에서 순차적으로 시도하는 구현이 현실적입니다:
MODELS=(
"qwen/qwen3-8b:free"
"google/gemini-2.0-flash-exp:free"
...
개인 학습 및 조사 목적은 :free를 사용하고, 중요한 코드 생성 작업은 claude-sonnet-4-5 (Anthropic 직접 결제)로 전환하여 사용하는 운영 방식이 현실적입니다. 프로젝트별로 분리하는 .envrc 접근법을 활용할 수 있습니다.
ANTHROPIC_API_KEY가 OpenRouter의 sk-or-v1- 형식인지 확인하세요. Anthropic의 sk-ant- 형식 키는 OpenRouter에서 사용할 수 없습니다.- OpenRouter의 모델명은 대소문자를 구분합니다.
https://openrouter.ai/models 에서 정확한 슬러그를 확인하세요.:free 접미사를 잊지 마세요.
Qwen3 계열 모델은 일본어에 능숙하지만, 시스템 프롬프트가 영어일 경우 응답이 영어로 나올 수 있습니다.
claude --system "당신은 한국어로 답변하는 AI 어시스턴트입니다." "코드의 버그를 찾아줘"
| 단계 | 작업 내용 |
|---|
| 1 | Claude Code CLI를 npm으로 설치 |
| ... | ANTHROPIC_BASE_URL을 OpenRouter로 지정 |
| 4 | --model 플래그 또는 설정 파일로 모델 지정 |
| 5 | 레이트 제한 대책을 넣어 실용적으로 사용 |
OpenRouter의 :free 모델은 레이트 제한이 있지만, 1원도 지불하지 않고 AI 페어 프로그래밍을 체험할 수 있는 가장 빠른 경로입니다. 비용 감각을 익힌 후 유료 플랜으로 전환하는 것이 낭비 없는 도입 흐름이라고 할 수 있습니다.
✍️ 본 기사 작성자: 주식회사 지모랩
지모랩은 하치오지에 거점을 두고 AI를 활용한 SaaS를 다수 개발하고 있습니다. 본 기사의 기술 검증 역시 그러한 개발 과정의 부산물입니다.
본 내용에 흥미를 느끼셨다면, 저희의 다양한 SNS 계정들도 팔로우해 주시면 감사하겠습니다!
