CLIProxyAPI

鏈路概覽

本教學最終形成以下呼叫鏈：

Chatbox → CLIProxyAPI → SOCKS5 代理 → CoffeeRouter → 上游模型

開始前請準備：

• 一個 CoffeeRouter 令牌，以及該令牌允許使用的準確模型 ID。
• Windows PowerShell。
• 如果需要透過代理存取 CoffeeRouter，一個已經執行的 SOCKS5 代理。本教學範例位址為 socks5://127.0.0.1:7897。
• 與 CLIProxyAPI 執行在同一台 Windows 電腦上的 Chatbox。

1. 下載並解壓縮 CLIProxyAPI

前往 CLIProxyAPI Releases 下載最新的 Windows amd64 壓縮檔，檔名通常類似：

CLIProxyAPI_<版本號>_windows_amd64.zip

解壓縮到您自己管理的目錄。發行包中通常包含 cli-proxy-api.exe、config.example.yaml、README 和授權檔案。

在同一目錄中新建 config.yaml，不要直接修改 config.example.yaml。後續升級時，範例檔案可能被新版本覆蓋；獨立的 config.yaml 更便於保留和遷移設定。

CLIProxyAPI 可提供 Web 管理中心，但程式本身沒有完整的原生桌面介面，Windows 建議透過 PowerShell 啟動。完成本教學後，工作目錄中至少應有：

• cli-proxy-api.exe
• config.yaml
• README.md 或 README_CN.md

2. 設定 config.yaml

以下是與本教學對應的最小範例。請替換三個佔位值，不要在公開文件、截圖或 Git 倉庫中儲存真實金鑰：

host: "127.0.0.1"
port: 8317

remote-management:
  allow-remote: false
  secret-key: "replace-with-a-strong-management-key"
  disable-control-panel: false

auth-dir: "~/.cli-proxy-api"

api-keys:
  - "replace-with-a-strong-local-key"

debug: false
logging-to-file: true

openai-compatibility:
  - name: "coffeerouter"
    base-url: "https://www.coffeerouter.ai/v1"
    api-key-entries:
      - api-key: "sk-your-coffeerouter-key"
        proxy-url: "socks5://127.0.0.1:7897"
    models:
      - name: "your-upstream-model-id"
        alias: "your-local-model-alias"

關鍵欄位說明：

欄位	用途
host: "127.0.0.1"	只允許本機連線，避免服務直接暴露到區域網路或公網
remote-management.secret-key	登入管理中心使用的獨立管理金鑰
頂層 api-keys	Chatbox 等本機用戶端存取 CLIProxyAPI 時使用的本機 Key
base-url	CoffeeRouter OpenAI 相容位址，必須保留一個 /v1
api-key-entries[].api-key	從 CoffeeRouter 後台取得的上游 Key
api-key-entries[].proxy-url	此上游 Key 使用的網路代理
models[].name	CoffeeRouter 中顯示的真實模型 ID
models[].alias	本機用戶端填寫的模型名稱，可自行定義

本教學假設 SOCKS5 代理確實監聽 127.0.0.1:7897。如果您的網路可以直接存取 CoffeeRouter，請刪除 proxy-url；不要填寫一個沒有執行的代理連接埠。

3. 啟動服務並開啟管理後台

在 PowerShell 中進入解壓縮目錄並啟動：

cd "D:\迅雷下載\CLIProxyAPI_7.2.74_windows_amd64"
.\cli-proxy-api.exe --config .\config.yaml

目錄名稱中的版本號只是範例，請以您實際下載的版本為準。

看到服務成功監聽 127.0.0.1:8317 後，不要關閉此 PowerShell 視窗；關閉視窗或按 Ctrl+C 會停止服務。

在瀏覽器開啟：

http://127.0.0.1:8317/management.html

使用 remote-management.secret-key 中設定的管理金鑰登入。管理中心與模型請求使用的本機 Key 不是同一個金鑰。

首次開啟管理中心時，CLIProxyAPI 可能需要下載管理面板資源。請保持 disable-control-panel: false，並確保目前網路能夠存取面板資源。

4. 在 CLIProxyAPI 中新增 CoffeeRouter

進入 AI Providers → OpenAI Compatible，新增或編輯一個提供商，填寫：

設定項	填寫內容
Name	coffeerouter
Base URL	https://www.coffeerouter.ai/v1
API key entry	CoffeeRouter 上游令牌，例如 sk-your-coffeerouter-key
Proxy URL	socks5://127.0.0.1:7897，僅在該代理確實執行時填寫
Test model	選擇目前令牌允許使用的模型

在 Custom models 中新增需要使用的模型：

• name：填寫 CoffeeRouter 中顯示的上游真實模型 ID。
• alias：填寫給本機用戶端使用的名稱，例如 coffee-claude-opus-4-8。
• 可以新增多個模型；每個模型都應使用唯一 alias。

儲存後返回列表。狀態正常時應顯示 Active，並顯示對應的模型數和 Key 數，例如 Models 1、Keys 1。

5. 理清兩個 API Key 和代理

模型請求鏈路中有兩個 API Key：

1. CLIProxyAPI 本機 Key：自行產生，寫入頂層 api-keys；Chatbox 請求本機 8317 連接埠時使用。
2. CoffeeRouter 上游 Key：在 CoffeeRouter 後台產生，寫入 openai-compatibility[].api-key-entries[].api-key；CLIProxyAPI 請求 CoffeeRouter 時使用。

此外，remote-management.secret-key 是第三個獨立的管理金鑰，只用於登入管理後台，不參與模型請求。

本教學的網路代理為：

socks5://127.0.0.1:7897

它負責 CLIProxyAPI 到 CoffeeRouter 的網路連線，不應填寫到 Chatbox 中。請先確認對應代理程式正在監聽連接埠 7897。

6. 使用 PowerShell 驗證本機鏈路

先檢查 8317 連接埠：

Test-NetConnection 127.0.0.1 -Port 8317

TcpTestSucceeded = True 表示本機連接埠已監聽，但不代表上游模型一定可用。繼續傳送一個實際請求：

$localKey = "replace-with-a-strong-local-key"
$body = @{
    model = "your-local-model-alias"
    messages = @(
        @{ role = "user"; content = "Reply only OK" }
    )
    stream = $false
} | ConvertTo-Json -Depth 5

Invoke-RestMethod `
    -Uri "http://127.0.0.1:8317/v1/chat/completions" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $localKey" } `
    -ContentType "application/json" `
    -Body $body

請將 $localKey 替換為頂層 api-keys 中的本機 Key，將模型替換為您設定的 alias。返回內容中出現 OK，表示完整鏈路已經打通。

成功鏈路為：

本機請求 → CLIProxyAPI → SOCKS5 → CoffeeRouter → 上游模型

7. 在 Chatbox 中設定並測試

在 Chatbox 中進入 Settings → Model Provider → Add → Add Custom Provider，填寫：

設定項	填寫內容
Name	CLIProxyAPI
API Mode	OpenAI API Compatible
API Key	CLIProxyAPI 頂層 api-keys 中的本機 Key
API Host	http://127.0.0.1:8317/v1
API Path	/chat/completions
Model	CLIProxyAPI 中設定的模型 alias

Chatbox 中不要填寫 CoffeeRouter 上游 Key。真實上游 Key 只儲存在 CLIProxyAPI 的 api-key-entries 中。

點擊 Check 或 Fetch 驗證設定，返回聊天頁面選擇對應模型並傳送測試訊息。

127.0.0.1 只代表目前裝置。本教學要求 Chatbox 和 CLIProxyAPI 執行在同一台電腦上；如果 Chatbox 在另一台裝置上，不能繼續使用這個位址，也不建議直接把管理後台暴露到區域網路或公網。

常見問題與安全提示

管理後台返回 404

確認 remote-management.secret-key 不是空值，並且 disable-control-panel 為 false。首次開啟時還需確保管理面板資源可以正常下載。

8317 連接埠檢測失敗

確認 PowerShell 啟動視窗仍在執行，檢查 config.yaml 是否有 YAML 縮排錯誤，並確認連接埠沒有被其他程式佔用。

返回 401 或 Invalid API Key

用戶端請求本機介面時必須使用頂層 api-keys 中的本機 Key；CoffeeRouter 上游 Key 只能填寫在 api-key-entries 中。

請求逾時或無法連線 CoffeeRouter

如果設定了 socks5://127.0.0.1:7897，請確認代理程式和連接埠確實可用。不需要代理時刪除 proxy-url 後再測試。

提示模型不存在

檢查本機請求使用的是模型 alias，並確認對應 name 與 CoffeeRouter 令牌管理頁顯示的模型 ID 完全一致。

官方資料

• CLIProxyAPI 官方倉庫
• 最新版本與 Windows 下載
• 官方設定範本
• CLIProxyAPI 官方指南