繁中 ▾

首頁指南

Claude Code Proxy 設定:搭配 OpenAI 相容 API

此 Claude Code Proxy 設定需五個步驟:取得金鑰、撰寫 LiteLLM 設定、啟動 Proxy、設定兩個環境變數並執行測試。大約需要十分鐘。

五個發光的墊腳石,從終端機延伸至伺服器,展示逐步 Proxy 設定過程

重點摘要

  1. 執行本地 LiteLLM Proxy 並轉發至 https://api.claudecodeproxyapi.com/v1
  2. 透過 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 將 Claude Code 指向 Proxy
  3. 將 Claude Code 發送的模型名稱對應至上游模型 uncensored
  4. 在啟動 CLI 前使用 curl 測試 Proxy

你需要什麼

  • 來自 金鑰頁面的 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
上游 401UPSTREAM_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% 的獎勵,不會讓你的餘額產生過期時效。

問答

Claude Code 需要哪些環境變數來設定 Proxy?

Proxy 位址的 ANTHROPIC_BASE_URL 以及 Proxy 接受的 token 的 ANTHROPIC_AUTH_TOKEN。ANTHROPIC_MODEL 可指定你定義的別名。請檢查目前的 Claude Code 文件以了解變更。

我需要在 ANTHROPIC_BASE_URL 加上 /v1 嗎?

否。使用 Proxy 位址(例如 http://localhost:4000),因為 CLI 會自行附加路徑。/v1 僅應出現在 Proxy 設定中的上游 api_base。

我可以使用 LiteLLM 以外的 Proxy 嗎?

可以。任何能將 Anthropic Messages 請求轉換為 OpenAI Chat Completions 的 Proxy 均可運作,例如 claude-code-router。將其上游指向 https://api.claudecodeproxyapi.com/v1 並使用模型 uncensored。

我的上游金鑰在設定檔中安全嗎?

請將其放在環境變數中,而非檔案內,如上方的設定所示。不要將金鑰提交到程式碼倉庫。

只差一張表單,即可取得金鑰

建立帳號、複製金鑰、更改基礎 URL。這就是整個設定過程。