free-claude-code 리뷰: Claude Code를 무료 LLM로 돌리는 오픈소스 프록시
free-claude-code 리뷰: Claude Code를 무료 LLM로 돌리는 오픈소스 프록시
Claude Code는 강력하지만 가격이 진입장벽이라는 평가가 많습니다. 월 $20 Pro 구독 또는 API 크레딧 결제가 부담스러운 1인 개발자나 학생에게는 더욱 그렇습니다.
free-claude-code는 이 진입장벽을 환경변수 2개로 무너뜨리는 오픈소스 프록시입니다. 본 글은 작동 원리, 지원 백엔드 6종 비교, 5분 설치 가이드, 그리고 솔직한 한계까지 정리합니다.
free-claude-code란 무엇인가
비유하자면 "전화 교환기"입니다. Claude Code가 Anthropic 본사로 전화를 걸면, 교환기가 그 전화를 NVIDIA·OpenRouter·DeepSeek 같은 다른 회사로 자동 연결합니다. 발신자(Claude Code)는 자기가 어디로 연결됐는지 모르고 그냥 통화합니다.
기술적으로는 로컬 8082 포트에서 FastAPI 기반 HTTP 프록시가 구동됩니다. ANTHROPIC_BASE_URL=http://localhost:8082로 설정하면 Claude Code의 모든 API 호출이 이 프록시를 통과합니다. 프록시는 Anthropic의 SSE 형식과 백엔드의 OpenAI chat / Anthropic Messages 형식을 양방향으로 변환합니다.
추가로 quota probe, title generation, prefix detection, suggestions, filepath extraction 같은 사소한 5종의 요청은 로컬에서 즉시 응답해 외부 호출 자체를 줄여줍니다. 무료 티어의 분당 요청 제한을 아끼는 데 결정적입니다.
지원 백엔드 6종 비교
| Provider | 비용 | Rate Limit | 특징 |
|---|---|---|---|
| NVIDIA NIM | 무료 | 40 req/min | 데일리 드라이버 추천. nvapi 키 발급만 필요 |
| OpenRouter | 무료/유료 혼합 | 모델별 상이 | 수백 개 모델, DeepSeek R1 무료 등 다수 |
| DeepSeek | 사용량 기반 | 모델별 상이 | DeepSeek 자체 Anthropic 호환 API 제공 |
| LM Studio | 완전 무료 | 무제한 | 로컬 GUI, 오프라인 동작 |
| llama.cpp | 완전 무료 | 무제한 | llama-server 직접 실행, 경량 |
| Ollama | 완전 무료 | 무제한 | Anthropic Messages 네이티브 지원 |
NVIDIA NIM의 분당 40 요청은 1인 개발자가 하루 종일 코딩해도 거의 막히지 않는 수준입니다. 보안에 민감한 코드는 LM Studio나 Ollama로 완전 오프라인 처리할 수 있고, 실험적 작업은 OpenRouter의 무료 모델로 돌릴 수 있습니다.
핵심 차별점: 모델 티어 매핑
이 프로젝트의 가장 인상적인 기능입니다. Claude Code는 작업 복잡도에 따라 내부적으로 Opus, Sonnet, Haiku 중 모델 티어를 선택합니다. 프록시는 그 결정을 가로채 각 티어를 다른 백엔드로 라우팅합니다.
MODEL_OPUS="nvidia_nim/moonshotai/kimi-k2.5"
MODEL_SONNET="open_router/deepseek/deepseek-r1-0528:free"
MODEL_HAIKU="lmstudio/unsloth/GLM-4.7-Flash-GGUF"
MODEL="nvidia_nim/z-ai/glm4.7"
위 설정의 의미는 다음과 같습니다. 무거운 추론은 Kimi K2.5(NIM 무료), 일반 작업은 DeepSeek R1(OpenRouter 무료), 빠른 응답은 LM Studio 로컬 모델, 폴백은 NIM의 GLM 4.7로 보냅니다. 비용은 0원이지만 작업 성격에 맞는 최적 모델이 자동 선택됩니다. 이른바 "티어 분리 전략"입니다.
설치 가이드: 5분이면 끝납니다
1단계: uv 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
uv python install 3.14
2단계: 클론 + 환경변수
git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
cp .env.example .env
.env 파일을 열어 NVIDIA_NIM_API_KEY=nvapi-xxx을 입력합니다. 키는 build.nvidia.com에서 무료 발급됩니다.
3단계: 프록시 실행
uv run uvicorn server:app --host 0.0.0.0 --port 8082
4단계: Claude Code 연결
다른 터미널에서:
ANTHROPIC_AUTH_TOKEN="freecc" \
ANTHROPIC_BASE_URL="http://localhost:8082" \
claude
ANTHROPIC_AUTH_TOKEN은 임의 문자열입니다. 프록시는 진짜 Anthropic 키를 요구하지 않습니다.
선호한다면 패키지 설치 방식도 가능합니다.
uv tool install git+https://github.com/Alishahryar1/free-claude-code.git
fcc-init
free-claude-code
추가 기능: 단순 프록시가 아닙니다
- Thinking Token 자동 변환: 백엔드가 보낸
<think>태그와reasoning_content를 Claude 네이티브 thinking 블록으로 변환합니다. 추론 모델의 사고 과정을 그대로 활용할 수 있습니다. - Heuristic Tool Parser: 무료 모델 중 일부는 tool call을 텍스트 형태로 토하는데, 이를 구조화된 tool use로 자동 파싱합니다.
- Discord/Telegram Bot: 트리 기반 메시지 스레딩, 세션 영속성, 라이브 진행상황 스트리밍, 보이스 노트 transcription을 지원합니다. 외출 중 휴대폰으로 코딩 작업을 지시할 수 있습니다.
- Subagent Control: Claude Code의 Task tool을 인터셉트해
run_in_background=False를 강제합니다. 무료 티어 쿼터 폭주를 막는 안전장치입니다. - Smart Rate Limiting: 능동적 rolling-window throttle과 429 exponential backoff가 내장되어 있습니다.
claude-pick: 모델을 매번 바꾸기 귀찮을 때
fzf 기반 인터랙티브 셀렉터입니다. 환경변수를 매번 수정하지 않고 실행 시점에 모델을 고를 수 있습니다.
brew install fzf
alias claude-pick="/path/to/free-claude-code/claude-pick"
한계: 정직하게 짚어봅니다
| 항목 | 한계 |
|---|---|
| Tool use 정확도 | Anthropic 모델 대비 보장 안 됨, 특히 무료 모델 |
| 지연시간 | NIM 무료티어는 분당 40 req. 동시 작업 많으면 throttle |
| 번역 레이어 | OpenAI chat → Anthropic 변환 시 일부 기능 손실 가능 |
| 안정성 | 자체 호스팅 프록시. 업타임 본인 책임 |
| 정직한 대안 | Claude Pro $20/월이 보장된 품질을 제공 |
특히 tool use는 무료 모델의 약점입니다. Claude의 tool 사용 정확도는 학습 단계에서 강하게 튜닝된 결과인데, 일반 LLM은 그 수준에 못 미칩니다. 프록시의 heuristic parser가 보완하지만 한계가 있습니다.
한국 1인 기업·개발자 관점에서 의미
free-claude-code는 Claude Code 자체를 대체하는 도구가 아니라 워크플로우의 선택지를 넓히는 도구입니다. 다음 상황에서 가치가 큽니다.
- 검증/실험 단계: Claude Code로 새 워크플로우를 테스트하고 싶지만 비용 약정은 부담스러울 때.
- 보안 민감 코드: 고객 데이터, 사내 코드베이스, 미공개 제품 코드는 외부 API에 보내기 어렵습니다. Ollama 로컬 백엔드가 답입니다.
- 티어 분리 운영: 핵심 작업은 진짜 Anthropic, 보일러플레이트는 무료 백엔드로 분산시키는 하이브리드 전략. 비용을 70-90% 절감 가능합니다.
- 원격 자율 코딩 실험: Discord/Telegram 봇으로 외부에서도 코딩 세션을 트리거할 수 있어 1인 운영의 시간 효율을 끌어올립니다.
반면 다음 상황에는 적합하지 않습니다.
- 클라이언트에 납품하는 프로덕션 코드 작성 (정확도 보장 필요)
- 복잡한 멀티스텝 tool 체인이 핵심인 작업
- 업타임 SLA가 필수인 자동화
결론
free-claude-code는 "Claude Code = 비싸다"는 인식을 환경변수 2개로 깨는 프로젝트입니다. NVIDIA NIM의 무료 분당 40 요청, 로컬 LLM 통합, 티어 분리 매핑이라는 세 가지 강점이 결합돼 1인 개발자에게 실용적인 선택지를 제공합니다.
다만 프로덕션 신뢰성과 tool use 정확도를 포기하는 트레이드오프는 명확합니다. "검증·실험 단계의 Claude Code 진입 도구" 또는 "비핵심 자동화의 비용 0원 운영 도구"로 사용하는 것이 합리적입니다. 진짜 품질이 필요한 작업에는 Claude Pro $20이 여전히 정직한 답입니다.
