• OpenRouter의
  :free

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

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

Claude Code, GitHub Copilot, Cursor——AI 코딩 어시스턴트는 20252026년에 걸쳐 폭발적으로 보급되었으나, 모두 월 $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 호출에 금전적 비용이 들지 않는다.

라이선스: 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 모델에는 다음과 같은 제약이 있다:

실제 운용 시에는 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 키로 전환하여 동작 확인을 수행한다.

월 사용료 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