ZCF
使用 ZCF 為 Claude Code 和 Codex 設定 CoffeeRouter。
接入前準備
開始前請準備：
- Node.js 22 或更高版本，以及可用的
npm/npx。 - 一個 CoffeeRouter 令牌。建議為 ZCF 單獨建立令牌，方便後續撤銷與稽核。
- 目前令牌允許使用的正確模型 ID。
- 需要使用的目標工具：Claude Code 或 Codex。ZCF 可以在初始化時協助安裝目標 CLI。
可以先閱讀 ZCF 官方文件 或查看 ZCF 官方儲存庫。ZCF 是第三方社群工具，選單名稱可能隨版本更新；本文依目前官方版本編寫。
地址與協定對照
ZCF 會依目標工具產生不同格式的設定，請勿混用以下地址：
| 目標工具 | ZCF 設定項 | 填寫內容 | 協定 |
|---|---|---|---|
| Claude Code | API 基礎 URL | https://www.coffeerouter.ai | Anthropic Messages |
| Codex | 基礎 URL | https://www.coffeerouter.ai/v1 | OpenAI Responses |
Claude Code 的地址不帶 /v1，因為客戶端會在基礎地址後拼接 Messages 請求路徑。Codex 的自訂 Provider 接收 OpenAI API Base URL，因此需要保留一個 /v1。
啟動 ZCF
在 PowerShell、終端或 WSL 中執行：
npx zcf
首次執行時，依提示選擇介面語言與 AI 輸出語言。如果 ZCF 目前管理的工具不是你需要的工具，在主選單選擇 切換工具，再選擇 Claude Code 或 Codex。
如果尚未設定目標工具，可以選擇 完整初始化；如果只需要修改 API 服務商，則選擇 設定 API。ZCF 偵測到現有設定時會提供備份、合併或保留選項，請先確認目前設定再繼續。
接入 Claude Code
1. 選擇自訂服務商
將目前工具切換為 Claude Code，進入 設定 API，選擇 自訂 API 設定。在服務商清單選擇 自訂設定；如果已存在 ZCF 管理的設定，則選擇新增設定。
2. 填寫 CoffeeRouter 設定
依提示填寫：
| 設定項 | 填寫內容 |
|---|---|
| 設定名稱 | CoffeeRouter |
| 認證類型 | API Key |
| API 基礎 URL | https://www.coffeerouter.ai |
| API Key | CoffeeRouter 令牌，例如 sk-your-api-key |
請勿把 API 基礎 URL 寫成 https://www.coffeerouter.ai/v1，否則 Claude Code 可能產生重複路徑。
3. 設定模型映射
ZCF 會繼續詢問主模型以及 Haiku、Sonnet、Opus 映射。請使用 CoffeeRouter 令牌管理頁顯示的完整模型 ID：
- 主模型：填寫日常預設使用的 Claude / Anthropic 相容模型 ID。
- Haiku、Sonnet、Opus 模型：依需求填寫對應模型 ID；不需要獨立映射時可留空。
- 如果令牌只有一個可用 Claude 模型，可以先只填寫主模型。
請勿自行縮寫或改寫模型名稱。模型 ID 必須與 CoffeeRouter 顯示的名稱完全一致。
4. 儲存並驗證
依需求將此設定設為預設設定。ZCF 會把所選設定套用到 ~/.claude/settings.json；接著執行：
claude
在 Claude Code 中傳送一則簡單測試訊息。如果出現 401，請檢查令牌；如果顯示模型不可用，請檢查令牌權限與模型 ID。
接入 Codex
1. 切換到 Codex
在 ZCF 主選單選擇 切換工具 → Codex，再進入 設定 API → 自訂 API 設定 → 自訂設定。
2. 填寫自訂 Provider
依提示填寫：
| 設定項 | 填寫內容 |
|---|---|
| 服務商名稱 | CoffeeRouter |
| 基礎 URL | https://www.coffeerouter.ai/v1 |
| API Key | CoffeeRouter 令牌，例如 sk-your-api-key |
| 模型名稱 | 目前令牌允許使用的模型 ID |
| 協定（自動寫入） | Responses |
目前 ZCF 會自動把自訂 Codex Provider 寫成 Responses 協定，不需要手動填寫協定。基礎 URL 只保留一個 /v1。
完成後不再新增其他 Provider，並將 CoffeeRouter 設為預設 Provider。ZCF 會更新 ~/.codex/config.toml 和 ~/.codex/auth.json。接著執行：
codex
傳送一個簡單的程式碼任務，確認模型可以正常回覆並呼叫基本工具。
可選：使用命令列自動設定
互動式設定更適合個人電腦，因為不會把真實令牌直接寫入命令歷史。以下命令只用於展示目前 ZCF 參數格式，請先替換模型 ID，並在實際執行時妥善保護令牌。
Claude Code
npx zcf i -s -T claude-code -p custom -t api_key -k "sk-your-api-key" -u "https://www.coffeerouter.ai" --api-model "your-claude-model-id"
Codex
npx zcf i -s -T codex -p custom -t api_key -k "sk-your-api-key" -u "https://www.coffeerouter.ai/v1" --api-model "your-model-id"
命令參數可能隨 ZCF 版本變更。用於自動化部署前，請執行 npx zcf --help 核對目前版本。
設定檔與安全
ZCF 目前使用以下本機路徑：
| 內容 | 預設路徑 |
|---|---|
| ZCF 全域設定 | ~/.ufomiao/zcf/config.toml |
| Claude Code 設定 | ~/.claude/settings.json |
| Codex Provider | ~/.codex/config.toml |
| Codex 憑證 | ~/.codex/auth.json |
切換或撤銷設定
需要切換已儲存的設定時，可以執行：
npx zcf config-switch -T claude-code
或：
npx zcf config-switch -T codex
要撤銷接入，請先在 CoffeeRouter 令牌管理頁停用或刪除對應令牌，再透過 ZCF 刪除該設定，或手動清理目標工具設定檔中的 CoffeeRouter Provider。只刪除本機設定不會讓已外洩的令牌失效。
常見問題
為什麼 Claude Code 地址不帶 /v1，而 Codex 要帶
兩款工具拼接請求路徑的規則不同。Claude Code 使用 Anthropic Messages 基礎地址，填寫站點根地址；Codex 使用 OpenAI Responses Base URL，填寫帶一個 /v1 的地址。
ZCF 會把請求轉送到自己的伺服器嗎
不會。ZCF 負責產生和切換本機設定，實際模型請求由 Claude Code 或 Codex 直接傳送到你設定的 CoffeeRouter 地址。
提示 401 或 API Key 無效
確認令牌複製完整、尚未過期、未被停用且有可用額度；同時檢查令牌的 IP 白名單等限制是否允許目前裝置存取。
提示 404 或路徑不存在
檢查地址是否與目標工具對應：Claude Code 使用 https://www.coffeerouter.ai，Codex 使用 https://www.coffeerouter.ai/v1。請勿重複新增 /v1。
模型無法使用
返回 CoffeeRouter 令牌管理頁，確認令牌允許使用該模型，並將模型 ID 原樣填入 ZCF。Claude Code 應優先選擇 Claude / Anthropic 相容的聊天模型；Codex 應選擇支援 OpenAI Responses 的模型。