free-claude-code
CLI 도구Alishahryar1/free-claude-code
Claude Code를 다양한 AI 제공업체에 연결해 주는 무료 프록시입니다.
개요
로컬 프록시 서버로, Claude Code의 API 호출을 NVIDIA NIM, OpenRouter, DeepSeek, Ollama 등 무료 또는 로컬 AI 제공업체로 라우팅합니다. Anthropic 구독 없이 Claude Code를 사용할 수 있으며, 스트리밍 응답, 도구 호출 및 모델 라우팅을 지원합니다.
README 미리보기
\n\n# 🤖 Free Claude Code\n\nUse Claude Code CLI, VS Code, JetBrains ACP, or chat bots through your own Anthropic-compatible proxy.\n\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://github.com/astral-sh/uv)\n[](https://github.com/Alishahryar1/free-claude-code/actions/workflows/tests.yml)\n[](https://pypi.org/project/ty/)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/Delgan/loguru)\n\nFree Claude Code routes Anthropic Messages API traffic from Claude Code to NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, or Ollama. It keeps Claude Code's client-side protocol stable while letting you choose free, paid, or local models.\n\n[Quick Start](#quick-start) · [Providers](#choose-a-provider) · [Clients](#connect-claude-code) · [Troubleshooting](#troubleshooting) · [Development](#development)\n\n\n\n\n \n\n\n## Star History\n\n\n \n \n \n \n \n \n \n\n\n## What You Get\n\n- Drop-in proxy for Claude Code's Anthropic API calls.\n- Six provider backends: NVIDIA NIM, OpenRouter, DeepSeek, LM Studio, llama.cpp, and Ollama.\n- Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers.\n- Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (Claude Code must opt in to Gateway model discovery; see [Model Picker](#model-picker)).\n- Streaming, tool use, reasoning/thinking block handling, and local request optimizations.\n- Optional Discord or Telegram bot wrapper for remote coding sessions.\n- Optional voice-note transcription through local Whisper or NVIDIA NIM.\n\n## Quick Start\n\n### 1. Install Requirements\n\nInstall [Claude Code](https://github.com/anthropics/claude-code), then install `uv` and Python 3.14.\n\nmacOS/Linux:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv self update\nuv python install 3.14\n```\n\nWindows PowerShell:\n\n```powershell\npowershell -ExecutionPolicy ByPass -c "irm https://astral.sh/u
FAQ (4)
문제 해결Claude Code가 시스템 메시지를 보낼 때 free-claude-code 프록시 422 오류를 수정하는 방법?
api/models/anthropic.py (95번째 줄)의 Message 모델을 업데이트하여 "system" 역할을 허용합니다: role: Literal["user", "assistant", "system"]. 편집 후 프록시를 다시 시작하십시오. 참고: 이는 로컬 패치로 업데이트 시 덮어쓰기됩니다. 영구적인 수정을 위해서는 소스 저장소를 업데이트해야 합니다.
문제 해결Free Claude Code (FCC)에서 모든 모델이 갑자기 작동하지 않는 이유는 무엇이며, 어떻게 해결할 수 있나요?
이 문제는 여전히 폐기된 NVIDIA Super 엔드포인트를 가리키는 FCC 버전 6.16.15에 영향을 미치며, 이로 인해 모든 모델 요청이 실패합니다. 재설치하거나 API 키를 교체해도 해결되지 않습니다. 해결 방법: fcc-update를 실행하여 6.16.16 이상으로 업그레이드하세요. 이 버전은 NVIDIA Super 선택 항목을 새로운 Ultra 엔드포인트로 자동 마이그레이션합니다. 그런 다음 FCC를 재시작하세요. 업데이트 후에도 계속 실패하면 FCC 설정 페이지를 열어 잘못된 모델 매핑을 수정하세요.
문제 해결macOS에서 Free Claude Code 메뉴 막대(트레이) 아이콘이 표시되지 않는 이유는 무엇이며, 어떻게 해결할 수 있나요?
이는 ~/Applications/Free Claude Code.app에서 FCC를 실행할 때 발생하는 알려진 문제입니다. 번들의 실행 파일이 번들 외부의 Python 인터프리터를 exec하는 셸 스크립트이기 때문에, macOS는 이러한 런처 패턴에 대해 상태 항목을 표시하지 않습니다(LSUIElement나 ad-hoc codesign -s -와 관계없이 지속됩니다). 서버는 여전히 실행되고 http://localhost:8082/admin도 정상 작동하지만, Open Admin / Restart Server / Quit 트레이 메뉴를 사용할 수 없게 됩니다. 해결 방법: pkill -f fcc-desktop으로 실행 중인 인스턴스를 종료한 다음, 터미널에서 fcc-desktop을 직접 실행하여 FCC를 시작하세요. 그러면 메뉴 막대 아이콘이 정상적으로 나타납니다. .app을 다시 클릭해도 아무 반응이 없는데, 이는 두 번째 인스턴스가 desktop.lock이 점유되어 있음을 감지하고 조용히 종료되기 때문입니다. 영구적인 해결을 위해서는 컴파일된 런처 바이너리 또는 자체 Python 실행 파일을 번들에 포함/링크하는 번들이 필요합니다.
문제 해결Claude Code에서 "There's an issue with the selected model. It may not exist or you may not have access to it" 오류를 수정하는 방법은 무엇인가요?
이 오류는 선택한 모델(예: claude-opus-5)에 대한 Claude Code의 요청이 백엔드에 의해 거부되었음을 의미합니다. 서버 로그에는 POST /v1/messages?beta=true에 대한 404 Not Found 응답이 반복적으로 나타나며, 이는 해당 모델에 대한 라우트/핸들러가 존재하지 않는다는 뜻입니다. 해결 방법: Claude Code 안에서 /model을 실행하여 프로바이더 또는 프록시가 실제로 지원하는 모델로 전환한 후 프롬프트를 다시 시도하세요. FCC와 같은 프록시를 통해 Claude Code를 라우팅하는 경우, 사용 중인 FCC 버전이 선택한 모델에 대한 엔드포인트를 등록하는지 확인하고, 설정을 변경한 후 서버를 재시작한 다음 fcc doctor를 실행하여 프로바이더 구성을 확인하세요.