LLM Wiki

Free Claude Code — Anthropic API 없이 Claude Code를 다른 모델에 연결하는 프록시

7 min read

Free Claude Code

Claude Code CLI / VSCode / IntelliJ의 Anthropic API 요청을 프록시로 가로채, NVIDIA NIM·OpenRouter·DeepSeek·LM Studio·llama.cpp로 우회 연결하는 오픈소스 프로젝트.

개요

Free Claude Code는 **“Claude Code를 무료 또는 저비용 대체 모델에 붙이는 프록시”**다. Anthropic API 키 없이도 Claude Code 인터페이스를 유지하면서, 실제 추론은 다른 프로바이더에서 수행하게 만든다.

핵심은 ANTHROPIC_BASE_URL 과 ANTHROPIC_AUTH_TOKEN 두 환경변수만 바꿔 Claude Code를 프록시 뒤로 붙인다는 점이다.

ANTHROPIC_AUTH_TOKEN="freecc" \
ANTHROPIC_BASE_URL="http://localhost:8082" \
claude

README 기준 지원 대상은 다음과 같다.

  • NVIDIA NIM — 무료 티어 40 req/min
  • OpenRouter — 무료/유료 다수 모델
  • DeepSeek — 직접 API 연결
  • LM Studio — 완전 로컬
  • llama.cpp / llama-server — 로컬 Anthropic 호환 엔드포인트

왜 중요한가

Claude Code 생태계에서 반복적으로 나타나는 흐름은 세 가지다.

  1. Claude Code UX는 유지하고 싶다
  2. Anthropic 직접 과금·제한은 줄이고 싶다
  3. 모델 선택권은 더 넓히고 싶다

Free Claude Code는 이 세 요구를 동시에 겨냥한다. 즉, Claude Code를 포크하지 않고도 **“Claude Code를 Anthropic 전용 클라이언트가 아니라 범용 AI coding shell처럼 재사용”**하려는 시도다.

핵심 기능

  • Drop-in replacement: 기존 Claude Code 수정 없이 환경변수만 변경
  • 5개 프로바이더 지원: NIM / OpenRouter / DeepSeek / LM Studio / llama.cpp
  • 모델별 매핑: Opus / Sonnet / Haiku를 서로 다른 모델로 라우팅
  • Thinking token 지원: 타 프로바이더 reasoning 출력을 Claude thinking block처럼 변환
  • Heuristic tool parser: 텍스트형 툴 호출을 구조화된 tool use로 복구 시도
  • Request optimization: 사소한 요청은 로컬에서 최적화
  • Rate limiting / backoff: 무료 티어·429 대응
  • Discord / Telegram bot: 원격 코딩 워크플로 지원
  • Subagent control: task 도구 인터셉트 편의를 위한 run_in_background=False 강제

설치 흐름

git clone https://github.com/Alishahryar1/free-claude-code.git
cd free-claude-code
cp .env.example .env
pip install uv
uv run uvicorn server:app --host 0.0.0.0 --port 8082

그 뒤 Claude Code를 다음처럼 실행한다.

ANTHROPIC_AUTH_TOKEN="freecc" ANTHROPIC_BASE_URL="http://localhost:8082" claude

README는 루트 URL을 써야 하며 http://localhost:8082/v1처럼 /v1를 붙이지 말라고 명시한다.

라우팅 예시

NVIDIA NIM

  • 무료 티어 40 req/min
  • 기본 추천 경로

OpenRouter

  • 무료 모델과 유료 모델을 함께 활용 가능
  • Opus / Sonnet / Haiku를 서로 다른 모델에 매핑 가능

DeepSeek

  • 직접 API 연결로 저비용 대안 제공

LM Studio / llama.cpp

  • 완전 로컬 추론 경로
  • Claude Code 인터페이스를 로컬 모델 프런트엔드처럼 활용 가능

해석

이 프로젝트는 2026-04-10-vibeproxy-gpt-claude-code처럼 Claude Code의 UI/작업방식은 유지한 채 백엔드 모델만 바꾸는 프록시 계열에 속한다. 다만 차이는 더 크다.

관심사 기준으로 보면 이 레포는 다음 세 축이 겹친다.

  • 무료 Claude Code 대안/우회 경로
  • LM Studio / llama.cpp 로컬 코딩 에이전트 실험
  • Claude Code UX를 유지한 채 모델 선택권을 넓히는 프록시 레이어

장점과 한계

장점

  • Claude Code 인터페이스/워크플로 재활용
  • 무료 또는 저비용 경로 확보
  • 로컬 모델까지 같은 UX로 붙일 수 있음
  • 모델별 라우팅으로 역할 분리 가능

한계 / 주의

  • Claude Code가 기대하는 동작과 타 프로바이더의 실제 응답 구조가 완전히 같지 않을 수 있음
  • tool use, thinking, streaming, subagent 동작은 호환 계층이 얼마나 잘 흉내 내느냐에 품질이 좌우됨
  • 무료 티어 기반 운영은 rate limit와 안정성 문제가 잦을 수 있음
  • Anthropic 공식 경로가 아니므로 장기적으로는 호환성 유지 비용이 계속 생김

특히 README에 heuristic parser, tool interception, thinking 변환이 강조된다는 것은, 이 프로젝트가 단순 API 포워더가 아니라 Claude Code가 기대하는 행위를 재구성하는 compatibility layer 라는 뜻이다. 강점이기도 하지만, 그만큼 깨질 지점도 많다.

실전 포지셔닝

이 프로젝트는 “Claude Code를 공짜로 쓴다” 보다, 더 정확히는 Claude Code를 범용 프런트엔드로 재활용한다는 관점에서 보는 편이 낫다.

추천되는 사용 맥락:

  • Claude Code UI/습관을 유지하고 싶을 때
  • Anthropic 직접 비용이 부담될 때
  • 로컬 LM Studio / llama.cpp 실험을 Claude Code UX로 해보고 싶을 때
  • OpenRouter / DeepSeek / NIM을 Claude Code 안에서 빠르게 비교하고 싶을 때

관련 노트

Source

그래프 뷰

백링크