Free Claude Code: 다양한 LLM 제공자를 Claude Code 프록시로 묶는 오픈소스 게이트웨이

9bow · 5월 25, 2026, 12:30오전

Free Claude Code 소개

Claude Code 같은 코딩 어시스턴트를 일상적으로 쓰다 보면 한 가지 한계에 자주 부딪힙니다. 클라이언트 자체는 훌륭하지만 백엔드 모델 선택지가 Anthropic API에 묶여 있어, 무료 크레딧을 제공하는 다른 추론 서비스나 로컬에 깔아둔 양자화 모델을 끌어다 쓰는 것이 쉽지 않다는 점입니다. Free Claude Code는 바로 이 지점에 끼어드는 프록시(proxy)입니다. Claude Code, VS Code 확장, JetBrains ACP, 그리고 옵션 챗봇이 보내는 Anthropic Messages API 트래픽을 가로채서, 사용자가 지정한 다른 제공자(provider)로 그대로 흘려보냅니다. 클라이언트 입장에서는 여전히 Anthropic API와 대화하고 있다고 믿지만, 실제 응답은 NVIDIA NIM이나 OpenRouter, 로컬 Ollama에서 나옵니다.

Free Claude Code는 Python 3.14 기반의 FastAPI 애플리케이션으로, /v1/messages, /v1/messages/count_tokens, /v1/models 같은 Anthropic 호환 엔드포인트를 그대로 노출합니다. 이 위에 모델 라우팅(routing) 계층이 얹혀 있어서, Claude Code가 요청한 Opus, Sonnet, Haiku 같은 모델 이름을 환경 변수 MODEL_OPUS, MODEL_SONNET, MODEL_HAIKU, MODEL 에 매핑된 실제 제공자 모델로 치환합니다. 결과적으로 한 프로젝트에서는 비싼 모델을 Anthropic으로, 다른 프로젝트에서는 무료 NVIDIA NIM 모델로 라우팅하는 식의 분리 운용이 가능해집니다.

Free Claude Code의 주요 기능

Free Claude Code는 단순한 API 우회 도구가 아니라, Claude Code의 프로토콜 호환성을 유지하면서 백엔드를 자유롭게 갈아끼울 수 있도록 설계된 게이트웨이입니다.

다중 제공자(Provider) 지원: NVIDIA NIM, Kimi, Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, Ollama, OpenCode Zen, OpenCode Go, Z.ai의 총 11개 백엔드를 지원합니다. 클라우드 추론과 로컬 추론을 한 프록시에서 함께 묶을 수 있습니다.
모델 티어별 라우팅: Opus, Sonnet, Haiku, 그리고 fallback 트래픽을 서로 다른 제공자로 보낼 수 있습니다. 예를 들어 무거운 추론은 NVIDIA NIM의 대형 모델로, 가벼운 요청은 로컬 Ollama로 분리할 수 있습니다.
Claude Code /model 피커 지원: 프록시의 /v1/models 엔드포인트를 통해 Claude Code의 네이티브 모델 선택 UI가 그대로 동작합니다. 단, Claude Code가 Gateway 모델 디스커버리를 옵트인해야 합니다.
프로토콜 정규화: 스트리밍(streaming), 도구 사용(tool use), 추론(reasoning) 및 thinking 블록 처리, 토큰 사용량 메타데이터를 모두 Anthropic SSE 형식으로 변환합니다.
로컬 Admin UI: /admin 경로에서 프록시 설정과 제공자 상태를 확인하고 검증할 수 있는 웹 UI를 제공합니다. 루프백(loopback) 접근만 허용해 외부 노출을 차단합니다.
옵션 통합: Discord와 Telegram 봇 어댑터를 통해 원격 코딩 세션을 만들 수 있고, 로컬 Whisper 또는 NVIDIA NIM을 통한 음성 노트 전사도 옵션으로 제공합니다.

Free Claude Code의 요청 흐름과 아키텍처

내부 동작을 한 줄로 정리하면 다음과 같습니다. 클라이언트는 Anthropic Messages API 형식으로 요청을 보내고, 프록시는 그 요청을 제공자별 전송 계층으로 번역해 응답을 받아온 뒤 다시 Anthropic SSE로 되돌려 보냅니다.

핵심 구성요소는 다음과 같습니다.

FastAPI 라우트 계층: /v1/messages, /v1/messages/count_tokens, /v1/models 같은 Anthropic 호환 엔드포인트를 노출합니다.
모델 라우팅(routing) 계층: Claude의 모델 이름을 환경 변수에 매핑된 실제 제공자 모델로 치환합니다.
OpenAI 호환 전송: NIM, OpenCode Zen, OpenCode Go, Z.ai는 OpenAI chat 스트리밍을 Anthropic SSE로 번역합니다.
Anthropic Messages 호환 전송: Wafer, OpenRouter, DeepSeek, LM Studio, llama.cpp, Ollama는 Anthropic Messages 스타일 전송을 그대로 사용합니다.
응답 정규화: 추론 블록, 도구 호출, 토큰 사용량 메타데이터, 제공자 오류를 Claude Code가 기대하는 형태로 정리합니다.
요청 최적화: Claude Code가 보내는 단순 프로브(probe) 요청은 프록시 단에서 로컬로 응답해 지연과 쿼터 소비를 줄입니다.

Free Claude Code 설치 및 사용법

Free Claude Code는 패키지 설치형 도구이며, 별도의 Docker 없이 Python 3.14와 uv 만 있으면 동작합니다. 저자는 Docker 통합 PR을 받지 않는다고 명시했으므로, 로컬 실행 또는 직접 구성한 원격 서버 위에서 운용하는 것을 전제로 합니다.

먼저 Claude Code CLI와 uv, Python 3.14를 설치합니다. macOS와 Linux 기준으로는 다음과 같습니다:

# Claude Code CLI 설치
npm install -g @anthropic-ai/claude-code

# uv 및 Python 3.14 설치
curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update
uv python install 3.14

그 다음 Free Claude Code 프록시를 설치합니다. 이 명령은 업데이트에도 동일하게 사용합니다.

uv tool install --force git+https://github.com/Alishahryar1/free-claude-code.git

프록시 서버를 띄우면 Uvicorn이 바인딩 주소를, 애플리케이션이 Admin UI 주소를 로그로 출력합니다.

fcc-server
# INFO:     Admin UI: http://127.0.0.1:8082/admin (local-only)

이후 http://127.0.0.1:8082/admin 에서 NVIDIA NIM 같은 기본 제공자를 구성하고, fcc-claude 명령으로 Claude Code를 프록시에 연결된 상태로 실행합니다. fcc-claude 는 Claude Code 프로세스에 프록시 URL, 인증 토큰, 모델 디스커버리 플래그, 그리고 자동 압축(auto-compaction)을 위한 190k 크기의 CLAUDE_CODE_AUTO_COMPACT_WINDOW 환경 변수를 함께 주입합니다.

Free Claude Code가 지원하는 클라이언트와 통합

Free Claude Code는 Claude Code CLI 외에도 여러 클라이언트를 동일한 프록시로 묶을 수 있도록 설계되었습니다. README에 명시된 지원 클라이언트는 다음과 같습니다.

Claude Code CLI: 가장 기본적인 사용 시나리오입니다. fcc-claude 가 프록시 주소와 토큰을 자동 주입합니다.
VS Code 확장: Claude Code의 VS Code 확장을 프록시에 연결해, 편집기 안에서 동일한 라우팅을 사용할 수 있습니다.
JetBrains ACP: JetBrains 계열 IDE의 Agent Coding Protocol(ACP)을 통해 IntelliJ, PyCharm 등에서도 프록시를 거치는 흐름이 가능합니다.
Discord와 Telegram 봇: 옵션 모듈인 messaging/ 어댑터를 통해 메신저에서 원격 코딩 세션을 열 수 있습니다.
음성 노트 전사: 로컬 Whisper 또는 NVIDIA NIM 기반 전사 모듈을 옵션으로 활용해 음성 입력을 텍스트 명령으로 변환할 수 있습니다.

확장 측면에서는 OpenAI 호환 제공자를 추가할 경우 OpenAIChatTransport 를, Anthropic Messages 스타일 제공자를 추가할 경우 AnthropicMessagesTransport 를 상속하면 됩니다. 새 제공자 메타데이터는 config.provider_catalog 에 등록하고, 팩토리 와이어링은 providers.registry 에 추가합니다. 메시징 플랫폼을 추가하려면 messaging/ 디렉토리의 MessagingPlatform 인터페이스를 구현하면 됩니다.

Free Claude Code 라이선스

Free Claude Code는 MIT 라이선스로 공개되어 있어, 개인 및 상업적 목적으로 자유롭게 사용하고 수정·재배포할 수 있습니다. 다만 사용하는 백엔드 제공자(NVIDIA NIM, OpenRouter, DeepSeek 등) 각각은 별도의 이용 약관과 데이터 처리 정책을 가지고 있으므로, 민감한 코드나 자료를 프록시로 흘리기 전에 어느 제공자로 트래픽이 라우팅되는지 한 번 확인하는 것이 좋습니다.

Free Claude Code 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~