Claude Code + OpenRouter Free 모델로 실현하는 「0원 AI 코딩 환경」 구축 3단계

OpenRouter의
:free

모델은 상용 이용이 가능한 LLM을 API 키 하나로 무료 사용 가능 - Claude Code의
--model

플래그와 환경 변수로 외부 엔드포인트를 향하게 하는 방법을 해설 - 월 0엔 스타트라도 Qwen3-235B, Llama-4-Maverick 등 고품질 모델을 사용할 수 있음

Claude Code, GitHub Copilot, Cursor——AI 코딩 어시스턴트는 2025~~2026년에 걸쳐 폭발적으로 보급되었으나, 모두 월 $20~~$100의 과금이 따른다. "개인 학습·OSS 기여·부업 프로젝트에 사용하고 싶지만, 우선 무료로 시도해보고 싶다"는 니즈는 뿌리가 깊다.

OpenRouter가 제공하는 ** :free 접미사(suffix) 모델**은 이 문제를 해결하는 엔트리 포인트가 된다. 본 기사에서는 그 메커니즘과 Claude Code (Anthropic 공식 CLI)를 OpenRouter를 경유하여 구동하는 설정 절차를 해설한다.

주의: Claude Code 자체는 Anthropic의 프로덕트이며, 공식적으로 지원되는 프록시 설정 이외에는 Anthropic의 이용 약관을 따른다. 본 기사의 내용은 2026년 5월 시점의 공개 문서에 기반한다.

OpenRouter (openrouter.ai)는 다양한 LLM 프로바이더에 대한 통합 API 게이트웨이를 제공하는 서비스다. 모델명 끝에 :free가 붙는 변형(variant)은 레이트 리밋(Rate Limit)이 있으며, 상용 이용은 각 모델의 라이선스에 따라 다르지만, API 호출에 금전적 비용이 들지 않는다.

모델명	파라미터 규모	특징
`qwen/qwen3-235b-a22b:free`	235B (MoE)	코딩·추론이 강력
`meta-llama/llama-4-maverick:free`	Maverick 사이즈	멀티모달 대응
`mistralai/mistral-7b-instruct:free`	7B	경량·고속
`google/gemma-3-27b-it:free`	27B	일본어도 비교적 안정

라이선스: Qwen3는 Apache 2.0, Llama 4는 Llama 4 Community License, Mistral은 Apache 2.0, Gemma 3는 Gemma Terms of Use (상용 이용에 조건 있음). 상용 프로덕트에의 편입은 반드시 각 라이선스를 확인할 것.

openrouter.ai에 접속하여 계정 생성
「Keys」 페이지에서 API 키를 생성
:free 모델만 사용하는 경우, 크레딧 충전은 불필요

# 동작 확인 (curl)
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
...

Claude Code는 환경 변수 ANTHROPIC_API_KEY에 더해, ANTHROPIC_BASE_URL로 베이스 URL을 교체할 수 있다. OpenRouter는 Anthropic Messages API 호환 엔드포인트 (/v1/messages)를 제공하고 있으므로, 이 메커니즘을 활용할 수 있다.

export ANTHROPIC_BASE_URL="https://openrouter.ai/api/v1"
export ANTHROPIC_API_KEY="sk-or-v1-xxxxxxxxxx" # OpenRouter 키를 사용

포인트: ANTHROPIC_API_KEY의 값은 OpenRouter 키로 교체한다. Claude Code는 내부적으로 이 키를 Authorization 헤더에 부가하기 때문에, OpenRouter가 요청을 받아 적절한 모델로 라우팅한다.

다음으로 모델을 지정한다:

claude --model "qwen/qwen3-235b-a22b:free" "이 코드의 버그를 고쳐줘"

또는 CLAUDE_MODEL 환경 변수로 고정할 수도 있다 (버전에 따라 다르므로 claude --help로 확인):

export CLAUDE_MODEL="qwen/qwen3-235b-a22b:free"
claude "関数のテストを書いて"

매번 export를 하는 것은 번거로우므로, direnv와 조합하면 프로젝트 디렉토리에 들어가는 것만으로 자동 적용할 수 있다.

# direnv 설치
brew install direnv # macOS
sudo apt install direnv # Ubuntu
...

보안 주의: .envrc는 .gitignore에 추가하여 리포지토리에 API 키가 포함되지 않도록 할 것.

# .gitignore
.envrc
.env.local

:free 모델에는 다음과 같은 제약이 있다:

제한 유형	기준
RPM (requests per minute)	10~20 rpm 정도 (모델에 따라 다름)
...

실제 운용 시에는 Backoff + Retry를 구현하거나, Claude Code의 타임아웃 (Timeout) 설정을 길게 잡는 것이 현실적이다:

# Python으로 OpenRouter를 직접 호출할 경우의 Retry 예시
import time
import httpx
...

용도별로 나누어 사용하는 것을 추천한다:

qwen/qwen3-235b-a22b:free

Qwen3-235B는 HumanEval・LiveCodeBench 계열의 벤치마크에서 GPT-4 급에 필적하는 스코어를 기록하고 있으며 (Qwen 팀의 공식 블로그 참조), 무료 모델 중에서는 최고 품질의 선택지 중 하나이다.

mistralai/mistral-7b-instruct:free

7B 모델이므로 응답이 빠르고, 레이트 리밋 (Rate Limit)에 걸릴 확률이 낮다. 반복적으로 실행하는 스크립트 계열의 CI 태스크에 적합하다.

google/gemma-3-27b-it:free

Gemma 3는 다국어 대응이 개선되어 있어, 일본어 README 생성이나 PR 설명문 작성에 사용하기 쉽다. 단, Gemma Terms of Use에 따라 특정 상업적 용도에는 제한이 있으므로 이용 전에 확인이 필요하다.

:free 모델은 OpenRouter 측의 수요에 따라 제공이 일시 중단될 수 있다.

대응: 폴백 (Fallback) 모델을 준비한다.

# 쉘 스크립트로 주/부 모델을 전환
PRIMARY_MODEL="qwen/qwen3-235b-a22b:free"
FALLBACK_MODEL="mistralai/mistral-7b-instruct:free"
...

큰 파일을 그대로 전달하면 max_tokens에 걸린다.

대응: 함수·클래스 단위로 분할하여 전달한다. git diff HEAD~1의 차분(diff)만 전달하는 것도 유효하다.

# 차분만 Claude에게 전달
git diff HEAD~1 | claude "이 변경 사항의 코드 리뷰를 해줘"

OpenRouter의 Anthropic 호환 엔드포인트(Endpoint)에서도 system_prompt 처리 방식이나 tool_use 구현이 네이티브 Anthropic API와 미묘하게 다를 수 있다.

대응: Claude Code의 고급 기능 (MCP 도구 호출 등)을 사용할 때는 네이티브 Anthropic API 키로 전환하여 동작 확인을 수행한다.

단계	내용
1	OpenRouter에서 계정 생성 및 API 키 취득
2	`ANTHROPIC_BASE_URL`과 `ANTHROPIC_API_KEY`를 설정하여 Claude Code를 연결
3	`direnv`로 `.envrc`에 설정을 집약하여 프로젝트 단위로 관리

월 사용료 0원으로 Claude Code와 유사한 코딩 경험을 시작할 수 있다. 모델의 품질과 속도에 만족한다면 OpenRouter에 크레딧을 추가하거나, Anthropic 네이티브 API로 전환하는 단계적인 이행도 자연스럽게 가능하다.

AI 코딩 환경에 대한 투자 장벽을 낮추고, 우선 실행해 보는 것이 중요하다.

OpenRouter 공식 문서
OpenRouter 모델 목록
Claude Code 공식 문서
Qwen3 기술 보고서 (Qwen 팀 공식)
Llama 4 Community License
direnv 공식

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

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

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

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

4-A~4-D에 해당하는 기술이 하나도 없는가? →
YES(사내 구성·환경 변수·사내 코드 미포함) -
코드 단편은 OSS / 공식 docs / 학습용 최소 예제뿐인가? →
YES -
인용한 OSS의 라이선스를 명기했는가? →
YES(Qwen3/Apache 2.0, Llama 4/Llama 4 Community, Mistral/Apache 2.0, Gemma 3/Gemma Terms) -
인용한 수치·벤치마크의 출처 URL을 기재했는가? →
YES(Qwen 팀 공식 블로그) -
제목에 숫자를 넣어 검색성을 높였는가? →
YES("3단계") -
태그는 Qiita의 관습에 맞는가? → 권장 태그:
`OpenRouter`
,`ClaudeCode`
,`LLM`
,`AI`
,`개발환경`

말미에 프로필 + lookupai 링크를 붙였는가? →
YES -
lookupai로의 자연스러운 유도가 1~2곳 있는가? →
YES(푸터에서 1곳) -
오타·탈자·코드 블록의 언어 지정은 OK인가? →
YES

Claude Code + OpenRouter Free 모델로 실현하는 「0원 AI 코딩 환경」 구축 3단계

요약

핵심 포인트

댓글