단 1달러도 내지 않고 Claude Code를 사용하는 방법 — 정확한 세팅 가이드

 

보통 Claude Code를 사용하려면 매월 20달러짜리 Anthropic(앤스로픽) 구독이 필수라고 생각합니다. 하지만 절대 그렇지 않습니다.

 

저 역시 한 달 20달러의 요금제를 결제할지 말지 20분 동안 고민하다가 이 사실을 깨달았습니다. 관련 문서를 깊게 파고들던 중 'Panaversity AI Agent Factory' 문서에서 실제 우회 설정 방법을 발견했고, 단 10분 만에 무료로 실행하는 데 성공했습니다.

아무도 미리 말해주지 않는 핵심 비밀은 바로 이것입니다. Claude Code는 백엔드 API에서 실제로 어떤 모델이 돌아가고 있는지 전혀 신경 쓰지 않습니다. 그저 사용자가 지정한 URL과 통신할 뿐이죠.

 

따라서 Gemini, DeepSeek, 또는 OpenRouter에 있는 30개 이상의 무료 모델을 연결해 주면 유료 버전과 완벽하게 똑같이 작동합니다. 스킬(Skills), MCP 서버, 서브 에이전트(Subagents) 등 모든 기능이 동일합니다.

 

지금부터 정확히 어떻게 세팅하는지 보여드리겠습니다.

 

⚡ 시작하기 전에 — 어떤 모델을 사용할 것인가?

우리에겐 3가지 선택지가 있습니다. 각기 장단점이 다르니 목적에 맞게 선택하세요.

구분	OpenRouter	Gemini	DeepSeek
비용	무료 (일일 제한 있음)	무료 (일일 제한 있음)	100만 토큰당 약 $0.028
지원 모델	30개 이상 (Qwen, Llama, Gemini 등)	Gemini 2.5 Flash	DeepSeek Chat + Reasoner
장점	압도적인 유연성, 다양한 모델 테스트 가능	가장 간단한 설정 과정	일관되고 강력한 품질
주의점	무료 모델이 주기적으로 교체됨	⚠️ 2025년 12월 기준 무료 한도 대폭 감소	완전한 무료는 아님

⚠️ 주의 (사람들이 잘 모르는 사실): Google은 2025년 12월에 Gemini의 무료 티어 한도를 조용히 축소했습니다. 대부분의 모델에서 일일 요청 한도가 50~80%가량 크게 줄어들었죠. 여전히 쓸 수는 있지만, 코딩 작업량이 많다면 금방 한계에 부딪힙니다.

반면 OpenRouter는 한 모델의 무료 한도가 끝나면 다른 무료 모델로 스위칭할 수 있어 훨씬 여유롭습니다.

이 글에서는 제가 매일 실무에서 사용 중이고 가장 유연한 OpenRouter를 기준으로 설명하겠습니다. (Gemini와 DeepSeek도 설정 파일 내용만 다를 뿐 전체적인 과정은 완벽히 똑같습니다.)

 

🧱 내부 동작 원리 (이해하고 넘어가기)

무작정 터미널을 열기 전에, 전체적인 구조를 이해해 두면 나중에 에러가 나도 당황하지 않습니다.

• 개발자(나) → ccr code → Claude Code Router (로컬) → OpenRouter API → 무료 모델

핵심은 로컬 라우터(Local Router)입니다. Claude Code는 로컬 환경의 3456 포트에서 실행되는 라우터와 통신합니다. 이 라우터가 Claude의 요청을 가로채서 OpenRouter(또는 Gemini 등)가 이해할 수 있는 형식으로 번역해 주는 역할을 합니다.

어떤 해킹이나 꼼수가 아닙니다. Anthropic 자체 생태계에 공식적으로 문서화된 합법적인 설정 방식입니다. 이 번역기 역할을 하는 도구가 바로 오픈소스인 claude-code-router(ccr)입니다.

 

🛠️ 본격적인 세팅: OpenRouter + Claude Code

Step 1: OpenRouter 무료 API 키 발급받기

1. openrouter.ai/keys에 접속합니다.
2. "Create Key" 버튼을 클릭하고 식별하기 편한 이름을 입력합니다.
3. 생성된 키를 복사해 둡니다. (sk-or-v1-... 형태로 시작합니다.) (무료 계정만으로도 30개 이상의 모델을 일일 한도 내에서 자유롭게 쓸 수 있으며, 카드 등록은 필요 없습니다.)

 

Step 2: 필수 패키지 설치하기

터미널을 열고 아래 명령어로 에이전트와 라우터를 모두 설치합니다.

npm install -g @anthropic-ai/claude-code @musistudio/claude-code-router

• 💡 방금 일어난 일: Claude Code(에이전트 본체)와 ccr 라우터(번역기)를 설치했습니다. 라우터가 없으면 Claude Code는 무조건 Anthropic의 유료 API 서버를 찾으려 하기 때문에 둘 다 반드시 필요합니다.

설치가 정상적으로 완료되었는지 버전을 확인해 봅니다.

claude --version   # Claude Code v2.x.x 출력됨
ccr version        # 라우터 버전 출력됨

 

Step 3: 구성(Config) 파일 생성하기

운영체제에 맞게 설정 파일을 만들어 줍니다. 이 파일이 라우터의 두뇌 역할을 합니다.

💻 Mac / Linux 사용자 터미널에 아래 코드 블록 전체를 복사해서 그대로 붙여넣고 엔터를 치세요.

mkdir -p ~/.claude-code-router ~/.claude
cat > ~/.claude-code-router/config.json << 'EOF'
{
  "LOG": true,
  "LOG_LEVEL": "info",
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "openrouter",
      "api_base_url": "[https://openrouter.ai/api/v1](https://openrouter.ai/api/v1)",
      "api_key": "$OPENROUTER_API_KEY",
      "models": [
        "qwen/qwen-coder-32b-vision",
        "google/gemini-2.0-flash-exp:free",
        "meta-llama/llama-3.3-70b-instruct:free",
        "qwen/qwen3-14b:free"
      ],
      "transformer": {
        "use": ["openrouter"]
      }
    }
  ],
  "Router": {
    "default": "openrouter,qwen/qwen-coder-32b-vision",
    "background": "openrouter,qwen/qwen-coder-32b-vision",
    "think": "openrouter,meta-llama/llama-3.3-70b-instruct:free",
    "longContext": "openrouter,qwen/qwen-coder-32b-vision",
    "longContextThreshold": 60000
  }
}
EOF

🪟 Windows 사용자 메모장을 열고 위 코드 블록 안의 JSON 내용 { ... } 만 복사한 뒤, 아래 경로에 config.json이라는 이름으로 저장하세요.

• 저장 경로: %USERPROFILE%\.claude-code-router\config.json

🚨 초보자 주의사항: JSON 내용 안에 있는 "$OPENROUTER_API_KEY" 부분을 본인의 실제 키로 수정하지 마세요! 이 부분은 문자 그대로 두어야 합니다. 라우터가 다음 단계에서 설정할 시스템 환경 변수를 읽어서 자동으로 처리합니다. 파일에 키를 직접 적어 넣으면 에러가 발생합니다.

 

Step 4: API 키 환경 변수로 고정하기

터미널을 껐다 켜도 API 키가 유지되도록 설정하는 단계입니다.

Mac (zsh 사용자 - 기본):

echo 'export OPENROUTER_API_KEY="Step1에서_복사한_실제_키"' >> ~/.zshrc
source ~/.zshrc

Mac (bash 사용자):

echo 'export OPENROUTER_API_KEY="Step1에서_복사한_실제_키"' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell - 관리자 권한으로 실행):

[System.Environment]::SetEnvironmentVariable('OPENROUTER_API_KEY', 'Step1에서_복사한_실제_키', 'User')

설정 후 열려있는 모든 PowerShell 창을 닫고 새로 열어주세요.

제대로 들어갔는지 확인해 볼까요?

echo $OPENROUTER_API_KEY  # 발급받은 키가 정상적으로 출력되어야 합니다.

 

Step 5: 실전 코딩 워크플로우 (터미널 2개 운용법)

가장 많이 헷갈려하시는 부분입니다. 실습할 때는 반드시 2개의 터미널 창이 띄워져 있어야 합니다.

 

🔥 터미널 1 (엔진 켜기) — 라우터 서버 실행

ccr start

✅ Service started successfully라는 메시지가 뜰 때까지 기다리세요. 이 터미널 창은 코딩하는 내내 절대 끄지 말고 백그라운드에 켜두어야 합니다.

 

💻 터미널 2 (운전석 앉기) — Claude Code 실행 새로운 터미널 탭이나 창을 엽니다.

cd 내가_작업할_프로젝트_폴더경로
ccr code

⏳ 참고: 처음 실행할 때는 라우터 초기화 때문에 10~20초 정도 멈춘 것처럼 보일 수 있습니다. 에러가 아니니 조금만 기다려주세요.

 

✅ 작동 테스트하기

Claude Code 프롬프트가 뜨면 가볍게 인사를 건네보세요.

hi

정상적인 답변이 돌아온다면 성공입니다. 좀 더 디테일하게 테스트하려면 아래처럼 물어보세요.

이 디렉토리에 어떤 파일들이 있고, 이 프로젝트가 전반적으로 무슨 역할을 하는지 설명해 줄래?

무료 모델이 내 로컬 폴더의 파일들을 직접 스캔하고 분석해서 대답한다면, 완벽한 '무료 에이전틱 코딩 환경' 구축에 성공하신 겁니다!

 

🔄 Gemini나 DeepSeek으로 변경하고 싶다면?

전체 과정은 똑같고, Step 3의 config.json 내용만 교체해 주면 됩니다.

 

[Gemini 설정]

• API 키 발급: aistudio.google.com/api-keys
• 환경 변수 이름: GOOGLE_API_KEY
• config.json의 Providers 부분:

"Providers": [{
  "name": "gemini",
  "api_base_url": "[https://generativelanguage.googleapis.com/v1beta/models/](https://generativelanguage.googleapis.com/v1beta/models/)",
  "api_key": "$GOOGLE_API_KEY",
  "models": ["gemini-2.5-flash-lite", "gemini-2.0-flash"],
  "transformer": { "use": ["gemini"] }
}]

 

[DeepSeek 설정]

• API 키 발급: platform.deepseek.com
• 환경 변수 이름: DEEPSEEK_API_KEY
• config.json의 Providers 부분:

"Providers": [{
  "name": "deepseek",
  "api_base_url": "[https://api.deepseek.com/v1](https://api.deepseek.com/v1)",
  "api_key": "$DEEPSEEK_API_KEY",
  "models": ["deepseek-chat", "deepseek-reasoner"],
  "transformer": { "use": ["openai"] }
}]

 

🚨 자주 발생하는 에러 해결법 (트러블슈팅)

1. command not found: ccr 에러가 떠요
   • npm 글로벌 설치 경로가 시스템 PATH에 잡혀있지 않아서 생기는 문제입니다. 터미널에 npm config get prefix를 입력해 나오는 경로 뒤에 /bin을 붙여서 ~/.zshrc 파일의 PATH 변수에 추가해 주세요.
2. 라우터는 켜졌는데 Claude 창에 아무것도 안 쳐져요 (먹통 현상)
   • 터미널 1에서 ccr start가 완전히 구동되기 전에 터미널 2에서 ccr code를 성급하게 실행해서 꼬인 현상입니다. 두 터미널을 모두 끄고, 터미널 1(서버 구동 완료) ➡️ 터미널 2(클로드 실행) 순서를 엄격히 지켜서 다시 켜보세요.
3. API key not found 에러가 떠요
   • Step 4의 환경 변수 설정이 영구적으로 저장되지 않았습니다. ~/.zshrc (또는 bashrc) 파일 최하단에 export 명령어가 제대로 적혀있는지 확인 후 source ~/.zshrc를 다시 실행해 보세요.
4. 한참 쓰다 보니 제한(Rate limits)에 걸렸다고 나와요
   • 해당 무료 모델의 일일 한도를 다 쓴 것입니다. config.json 파일에서 default 모델 이름을 OpenRouter에서 지원하는 다른 무료 모델(예: qwen/qwen3-14b:free)로 바꾸고 라우터를 재시작하세요.

 

💡 결론: 굳이 돈 낼 필요 있을까?

"무료 모델이 유료인 Claude 3.5 Sonnet이나 Opus랑 성능이 완벽하게 똑같나요?"라고 묻는다면 그건 아닙니다. 매우 복잡하고 단계가 긴 추론 작업에서는 당연히 유료 Claude 모델이 앞섭니다.

 

하지만 실무에서 써본 제 결론은 이렇습니다. 코드베이스 파악, 보일러플레이트(기본 틀) 생성, 에러 원인 분석, 테스트 코드 작성 등 일상적인 개발 작업의 90%는 OpenRouter의 무료 모델들로 진심으로 충분합니다. 특히 Qwen-Coder-32B 모델의 코딩 실력은 기대 이상입니다.

 

현재 매월 20달러를 내고 Claude Pro를 쓰는 사람들은 대부분 세팅의 귀찮음을 피하기 위한 '편의성' 비용을 지불하고 있는 셈입니다. 여러분이 새로운 기술을 학습 중이거나, 사이드 프로젝트를 만드는 정도라면 일단 무료 버전으로 시작해 보세요. 돈은 정말 성능의 한계에 부딪혔을 때 내도 늦지 않습니다.