Star 歷史

核心功能

• 即插即用：完全相容 Claude Code 的 Anthropic API 調用代理。
• 八大供應商後端：支援 NVIDIA NIM、Kimi、Wafer、OpenRouter、DeepSeek、LM Studio、llama.cpp 和 Ollama。
• 按模型路由：可將 Opus、Sonnet、Haiku 或預設流量分別導向不同的供應商。
• 原生模型選擇器：透過代理的 /v1/models 端點支援 Claude Code 原生的 /model 指令（需啟用 Gateway 模型發現功能）。
• 完整協定支援：支援串流（Streaming）、工具調用（Tool use）、推理/思考塊（Reasoning/Thinking block）處理以及本地請求優化。
• 通訊軟體整合：可選的 Discord 或 Telegram 機器人封裝，實現遠端編碼協作。
• 語音轉文字：支援透過本地 Whisper 或 NVIDIA NIM 進行語音訊息轉錄。

快速開始

1. 安裝需求

首先安裝 Claude Code，接著安裝 uv 和 Python 3.14。

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv self update
uv python install 3.14

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv self update
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 為例：

NVIDIA_NIM_API_KEY="您的金鑰"
MODEL="nvidia_nim/z-ai/glm4.7"
ANTHROPIC_AUTH_TOKEN="freecc"

您可以為 ANTHROPIC_AUTH_TOKEN 自定義一個本地秘密；Claude Code 會將相同的值傳回此代理。僅在本地/私人測試時可留空。

3. 啟動代理伺服器

uv run uvicorn server:app --host 0.0.0.0 --port 8082

另一種安裝方式（作為工具安裝）：

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

fcc-init 會從模板建立全域設定檔 ~/.config/free-claude-code/.env。

4. 執行 Claude Code

將 ANTHROPIC_BASE_URL 指向代理根目錄（注意：末尾不要加 /v1）。如果您想使用 /model 指令列出此代理的模型，請設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1。

PowerShell:

$env:ANTHROPIC_AUTH_TOKEN="freecc"; $env:ANTHROPIC_BASE_URL="http://localhost:8082"; $env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"; claude

Bash:

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

選擇供應商

模型值的格式如下：

供應商ID/模型/名稱

MODEL 是後備選項。MODEL_OPUS、MODEL_SONNET 和 MODEL_HAIKU 會覆蓋 Claude Code 發送的對應層級請求。

(各供應商詳細設定請參閱原 README 下方的摺疊區塊)

連接 Claude Code

Claude Code CLI

使用上述「快速開始」中的環境變數啟動即可。

VS Code 擴充功能

打開設定，搜尋 claude-code.environmentVariables，選擇 在 settings.json 中編輯，並加入：

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "http://localhost:8082" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "freecc" },
  { "name": "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "value": "1" }
]

重新載入擴充功能。如果顯示登入畫面，請選擇 Anthropic Console 路徑登入一次；環境變數生效後，本地代理仍會處理模型流量。

JetBrains ACP

編輯已安裝的 Claude ACP 設定：

• Windows: C:\Users\%USERNAME%\AppData\Roaming\JetBrains\acp-agents\installed.json
• Linux/macOS: ~/.jetbrains/acp.json

在 acp.registry.claude-acp 下設定環境變數：

"env": {
  "ANTHROPIC_BASE_URL": "http://localhost:8082",
  "ANTHROPIC_AUTH_TOKEN": "freecc",
  "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
}

修改後重啟 IDE。

模型選擇器 (Model Picker)

Claude Code 2.1.126 或更新版本可以在 ANTHROPIC_BASE_URL 指向此代理時，透過 /v1/models 響應自動填充 /model 列表。 注意：較新版本需要明確設定 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 才能啟用此功能。

代理會自動將選擇器中的 ID 路由回真實供應商，因此啟動後無需修改 .env 或使用其他啟動腳本。 每個供應商模型都有一個 (no thinking) 變體，適用於不支援「思考」功能或自適應思考請求失敗的情況。

常見問題排除

Claude Code 顯示 undefined ... input_tokens 或響應異常

請先更新至最新 commit。舊版本可能會在串流響應中發送無效的元數據。接著檢查：

• ANTHROPIC_BASE_URL 為 http://localhost:8082（不要加 /v1）。
• 代理是否正確為 /v1/messages 返回 SSE 事件。
• server.log 中是否有上游 400/500 錯誤。

llama.cpp 或 LM Studio 返回 HTTP 400

這通常表示本地運行時在代理開始串流前拒絕了請求。請檢查：

• 本地伺服器支援 POST /v1/messages。
• 模型和運行時支援請求的上下文長度和工具調用。
• 基礎 URL 必須包含 /v1。

串流中途斷開

incomplete chunked read 等錯誤通常來自上游供應商或網關。請嘗試減少併發、增加超時時間或稍後重試。

運作原理

Claude Code CLI / IDE
        |
        | Anthropic Messages API
        v
Free Claude Code 代理伺服器 (:8082)
        |
        | 供應商特定的請求/串流適配器
        v
NIM / Kimi / Wafer / OpenRouter / DeepSeek / LM Studio / llama.cpp / Ollama

開發與貢獻

專案結構

• server.py: ASGI 入口點。
• api/: FastAPI 路由、服務層、路由與優化。
• providers/: 供應商傳輸方式、註冊與速率限制。
• messaging/: Discord/Telegram 適配器、工作階段與語音。
• config/: 設定、供應商目錄與日誌。

常用指令

uv run ruff format   # 格式化代碼
uv run ruff check    # 代碼檢查
uv run ty check      # 類型檢查
uv run pytest        # 執行測試

授權條款

MIT License。詳見 LICENSE 檔案。