你需要什麼
- 來自 金鑰頁面的 API 金鑰。使用 Google 或電子郵件與密碼註冊,然後一鍵領取 $0.50 免費試用額度。
- Python 3.9 或更新版本,用於安裝 Proxy。
- 已在您的機器上安裝並正常運作的 Claude Code。
為什麼需要 Proxy?Claude Code 使用 Anthropic 的 Messages 格式,而我們的 API 使用 OpenAI 的 Chat Completions 格式,模型 ID 為 uncensored。Proxy 負責在兩者之間轉換格式。如果你想先了解背景,請閱讀 Proxy 故障排除指南。該模型為開放權重模型,並非 Claude,因此在複雜的多步驟任務上預期會有不同的行為。
步驟 1:安裝 Proxy
使用虛擬環境,使 Proxy 的相依性與您的專案保持隔離:
python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'
LiteLLM 是第三方開源軟體。以下命令與設定鍵值在撰寫時符合其公開文件,但若參數有變更,請檢查其最新文件。
步驟 2:撰寫設定
建立 config.yaml。model_name 是客戶端發送的模型名稱。litellm_params 區塊指定轉發目標。openai/ 前綴告知 LiteLLM 連線至 OpenAI 相容伺服器。
cat > config.yaml <<'EOF'
model_list:
- model_name: claude-sonnet
litellm_params:
model: openai/uncensored
api_base: https://api.claudecodeproxyapi.com/v1
api_key: os.environ/UPSTREAM_KEY
EOF
別名 claude-sonnet 僅為範例,並非必要。Claude Code 可能會發送多種不同的模型名稱,例如主要模型與用於背景任務的小型模型。請為 Proxy 記錄中出現的每個名稱新增一筆 model_list 條目,全部指向同一個上游。將所有別名指向 uncensored 是可以的,因為只有一個模型。
金鑰從環境變數讀取,因此不會落入您可能會提交的檔案中。
步驟 3:啟動 Proxy
export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000
保持此終端機開啟。您應看到伺服器正在監聽 4000 連接埠。現在從 Proxy 側使用 Anthropic 格式的測試請求檢查上游路徑,這是 Claude Code 會發送的格式:
curl http://localhost:4000/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: sk-local-anything" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet",
"max_tokens": 200,
"messages": [{"role": "user", "content": "Reply with the word ready."}]
}'
若 JSON 回覆的內容包含單字 "ready",表示端到端的翻譯運作正常:Anthropic 格式輸入,輸出至 https://api.claudecodeproxyapi.com/v1,再轉回。如果你在 LiteLLM 設定檔中設定了主金鑰,請用它取代 sk-local-anything。
步驟 4:將 Claude Code 指向 Proxy
Claude Code 從環境變數讀取其 API 位址與權杖。在您啟動 CLI 的 Shell 中設定它們:
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude
在此處使用 Proxy 的位址,但不要加上 /v1 後綴,因為 CLI 會自行加入路徑。token 只需滿足 Proxy 即可,因為真正的上游金鑰是你匯出為 UPSTREAM_KEY 的那個。如果你使用 CLI 的設定檔來設定環境變數而非使用 Shell,請將這三個名稱也放在那裡。Claude Code 的環境變數名稱可能會在不同版本間變更,如果某些設定被忽略,請對照目前的 Claude Code 文件進行驗證。
步驟 5:執行首次任務並觀察記錄
從小處開始。要求 CLI 解釋單一檔案或為函式新增註解。Proxy 終端機應顯示每步請求。記錄出現的模型名稱;若不在 model_list 中,Proxy 會回傳錯誤,請將其加入並重新啟動。
此處函式呼叫很重要,因為 CLI 透過工具讀取檔案和編輯程式碼。API 支援 tools、tool_choice 和串流 tool_calls,Proxy 會進行轉換。對工具架構的遵循度較低會導致編輯失敗或步驟重複。發生時,縮小任務範圍並重試,再判斷設定是否故障。
上下文視窗為 100,000 token(提示詞與完成內容合計)。超過此限制的長會話會失敗,請為新任務開啟新會話。成本極低:每 1M 輸入 token $0.15,每 1M 輸出 token $0.50。輸入 20,000 token、輸出 800 token 的請求成本為 $0.003 + $0.0004 = $0.0034。見 定價頁面 進行儲值,此站接受加密貨幣(TRC20 上的 USDT、Base 上的 USDC)付款。
故障排除
| 您會看到的內容 | 原因 | 修復方法 |
|---|---|---|
| 連線被拒絕 | Proxy 未運行或連接埠不同 | 啟動它並在 ANTHROPIC_BASE_URL 中匹配連接埠 |
| Proxy 404 或「找不到模型」 | CLI 發送的模型名稱不在設定中 | 將該名稱加入 model_list |
| 上游 401 | UPSTREAM_KEY 錯誤或為空 | 在 Proxy 的 Shell 中重新匯出金鑰並重新啟動 |
429 錯誤與 concurrency 相關 | 超過 8 個並行請求(試用期間為 2 個) | 減少並行代理數量 |
429 錯誤且rate_limited | 每分鐘超過 300 個請求(試用為 60) | 退避並重試 |
429 帶有 Retry-After: 5 | 暫時過載 | 五秒後重試 |
| 串流輸出停滯 | 串流請求會佔用其槽位直到結束 | 在 CLI 中取消它以釋放槽位 |
對於此處未涵蓋的任何事項,寫信給支援時請附上 X-Request-Id 回應標頭。文件 列出所有支援的參數。
使其成為永久設定
每次手動輸入 export 很麻煩。將 Proxy 啟動放入小型腳本,並將客戶端變數放入別名,這樣只需一個命令即可啟動所有服務:
cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh
alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'
因為這些變數僅針對該單一指令設定,你的正常 claude 指令仍會對其預設設定運作。將別名加入你的 Shell 設定檔。使用 chmod 700 等檔案權限保護腳本,因為它包含你的金鑰。
切換回原本設定
如果你在當前 Shell 匯出了變數,請執行 unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL 並重新啟動 CLI。API 端沒有任何變更,因此無需撤銷任何操作。
監控你的餘額與支出
API 的每個回應都會帶有 X-Balance-USD標頭,顯示你金鑰剩餘的額度。LiteLLM 在某些設定下可以將上游標頭傳遞過來,但最可靠的方式是偶爾直接呼叫上游來查看餘額:
curl -i https://api.claudecodeproxyapi.com/v1/models \
-H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd
Agent 會話會悄悄增長。每個步驟都會重新發送工作上下文,因此長時間的會話每次請求的成本比短會話更高。為每個任務啟動新的會話可保持輸入內容較小並降低費用。以公告價格(輸入每 1M token $0.15,輸出每 1M token $0.50)計算,一次請求輸入 50,000 token 且輸出 1,000 token 的成本為 50,000 x $0.15 / 1M = $0.0075 加上 $0.0005,總計 $0.008。二十次此類請求總計為 $0.16。
儲值金額從 $20 到 $500 不等,且為整數金額,透過本站以 TRC20 上的 USDT 或 Base 上的 USDC 支付。額度永不過期,因此較大的儲值搭配 +5%、+10% 或 +15% 的獎勵,不會讓你的餘額產生過期時效。
