CC Switch CLI

使用 CC Switch CLI 為多款 AI 程式設計 Agent 設定並切換 CoffeeRouter Provider。

準備工作

開始前請準備：

一個 CoffeeRouter 令牌。建議為每個 Agent 工具建立獨立令牌，方便限制模型、額度和 IP，並可單獨撤銷。
目前令牌允許使用的準確模型 ID。模型名稱必須與 CoffeeRouter 令牌管理頁顯示的名稱完全一致。
已安裝需要接入的目標工具。
受支援的終端。Windows 建議使用 Windows Terminal 或 PowerShell，macOS/Linux 使用常用終端即可。

首次切換 Provider 前，請至少執行一次目標工具，讓它建立本機設定目錄：

claude --help
codex --help
gemini --help
opencode --help
openclaw --help

Hermes 使用者可以先執行 Hermes，或確認 ~/.hermes 目錄已存在。目標工具尚未初始化時，CC Switch CLI 會基於安全考量跳過即時設定寫入。

位址與協定對照

不同工具會自行拼接不同的請求路徑，請嚴格按照下表填寫：

目標應用	Base URL	API 格式	本機代理
Claude Code	`https://www.coffeerouter.ai`	`Anthropic`	關閉
Codex	`https://www.coffeerouter.ai/v1`	`Responses`	關閉
Gemini CLI	`https://www.coffeerouter.ai`	Gemini 原生 API	關閉
OpenCode	`https://www.coffeerouter.ai/v1`	OpenAI Compatible	不支援，也不需要
Hermes	`https://www.coffeerouter.ai/v1`	`chat_completions`	不支援，也不需要
OpenClaw	`https://www.coffeerouter.ai/v1`	`openai-completions`	不支援，也不需要

Claude Code 和 Gemini CLI 接收站點根位址，並自行拼接 Anthropic Messages 或 Gemini /v1beta 路徑。其餘 OpenAI 相容工具需要保留一個 /v1。

安裝 CC Switch CLI

CC Switch CLI 不提供 npm 或 npx 安裝方式。請使用官方發布的二進位檔案。

macOS 或 Linux

使用官方安裝腳本：

curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

預設安裝到 ~/.local/bin。macOS 也可以使用 Homebrew：

brew install cc-switch-cli

透過 Homebrew 安裝後，請使用 brew upgrade cc-switch-cli 更新，不要混用 CC Switch CLI 內建更新功能。

Windows

從 CC Switch CLI Releases 下載 cc-switch-cli-windows-x64.zip，解壓縮後執行 cc-switch.exe，或將其放入由你管理的 PATH 目錄。

安裝完成後檢查：

cc-switch --version
cc-switch --help

啟動並選擇目標應用

執行：

cc-switch

進入全螢幕介面後，按照介面底部的按鍵提示完成以下操作：

切換到需要設定的應用，例如 Claude、Codex 或 Gemini。
開啟 Providers / 供應商。
選擇 Add Provider / 新增供應商。
Provider 範本選擇 Custom。

TUI 快速鍵可能隨版本調整，請以目前介面底部顯示的提示為準。

在 CC Switch CLI 中選擇目標應用

新增 Custom Provider

接入 Claude Code

切換到 Claude 應用並新增 Custom Provider，填寫：

設定項	填寫內容
Name	`CoffeeRouter`
Base URL	`https://www.coffeerouter.ai`
API Key	CoffeeRouter 令牌，例如 `sk-your-api-key`
API Key Field	`ANTHROPIC_API_KEY`
API Format	`Anthropic`
Main / Haiku / Sonnet / Opus	按需填寫目前令牌允許使用的 Claude 模型 ID
Local Proxy	關閉

Base URL 不要新增 /v1。CoffeeRouter 已提供 Anthropic Messages 相容介面，因此無需選擇 OpenAI Chat/Responses 轉換，也無需啟用本機代理。

如果令牌只允許一個 Claude 模型，可以先把同一模型 ID 用作主模型，並按需設定 Haiku、Sonnet、Opus 映射。

填寫 Claude Code 的 CoffeeRouter Provider

接入 Codex

切換到 Codex 應用並新增 Custom Provider，填寫：

設定項	填寫內容
Name	`CoffeeRouter`
Base URL	`https://www.coffeerouter.ai/v1`
API Key	CoffeeRouter 令牌，例如 `sk-your-api-key`
Upstream API Format	`Responses`
Model Mapping / Model Catalog	至少新增一個目前令牌允許使用的模型 ID
Proxy Takeover / Local Proxy	關閉

目前版本主要透過 Model Mapping / Model Catalog 管理 Codex 模型。在 Responses 模式下，它用於直連選擇上游模型，並不代表啟用協定轉換或本機代理。如果介面顯示 Model 欄位，也應填寫相同的完整模型 ID。不要選擇 Chat 格式，也不要把位址寫成 /v1/v1。

填寫 Codex 的 CoffeeRouter Provider

接入 Gemini CLI

切換到 Gemini 應用並新增 Custom Provider，填寫：

設定項	填寫內容
Name	`CoffeeRouter`
Auth Type	`API Key`
API Key	CoffeeRouter 令牌，例如 `sk-your-api-key`
Base URL	`https://www.coffeerouter.ai`
Model	目前令牌允許使用的 Gemini 模型 ID

Gemini CLI 會把 Base URL 寫入 GOOGLE_GEMINI_BASE_URL，並自行請求 /v1beta/models/...，因此這裡不要新增 /v1 或 /v1beta。

填寫 Gemini CLI 的 CoffeeRouter Provider

接入其他工具

CC Switch CLI 還可以直接寫入 OpenCode、Hermes 和 OpenClaw 的 Provider 設定。

OpenCode

設定項	填寫內容
Provider Package	`@ai-sdk/openai-compatible`
Base URL	`https://www.coffeerouter.ai/v1`
API Key	CoffeeRouter 令牌
Model ID	目前令牌允許使用的完整模型 ID
Model Name / Context / Output Limit	選填，按模型能力填寫

Hermes

設定項	填寫內容
API Mode	`chat_completions`
Base URL	`https://www.coffeerouter.ai/v1`
API Key	CoffeeRouter 令牌
Models	至少新增一個完整模型 ID；第一個模型作為預設模型

OpenClaw

設定項	填寫內容
API Protocol	`openai-completions`
Base URL	`https://www.coffeerouter.ai/v1`
API Key	CoffeeRouter 令牌
Models	至少新增一個完整模型 ID

儲存 OpenClaw Provider 後，還需要在 CC Switch CLI 中把 CoffeeRouter Provider 和對應模型設為預設值。OpenCode、Hermes 和 OpenClaw 不使用 CC Switch CLI 的本機代理功能。

啟用並驗證

儲存 Provider 後返回供應商列表，選取 CoffeeRouter，再按照介面底部提示執行 Switch / Activate。第一次切換時，如果 CC Switch CLI 偵測到現有設定，請先閱讀匯入或備份提示，避免覆蓋仍需保留的設定。

啟用 CoffeeRouter Provider 並驗證目前設定

可以在終端中檢查目前 Provider：

cc-switch --app claude provider current
cc-switch --app codex provider current
cc-switch --app gemini provider current

然後重新啟動對應 Agent CLI 並傳送一則簡單測試訊息。未指定 --app 時，CC Switch CLI 預設管理 Claude。

可選使用命令列設定

建議使用 TUI 輸入令牌。以下命令適合自動化情境，但真實 API Key 可能出現在終端歷史、處理程序列表或錄影中。範例只使用占位令牌。

Claude Code

cc-switch --app claude provider add --name CoffeeRouter --id coffeerouter --base-url https://www.coffeerouter.ai --api-key sk-your-api-key --model your-claude-model-id --api-format anthropic --api-key-field api-key
cc-switch --app claude provider switch coffeerouter

Codex

cc-switch --app codex provider add --name CoffeeRouter --id coffeerouter --base-url https://www.coffeerouter.ai/v1 --api-key sk-your-api-key --model your-model-id --api-format responses
cc-switch --app codex provider switch coffeerouter

Gemini CLI

cc-switch --app gemini provider add --name CoffeeRouter --id coffeerouter --base-url https://www.coffeerouter.ai --api-key sk-your-api-key --model your-gemini-model-id
cc-switch --app gemini provider switch coffeerouter

provider add 是非互動命令，不能省略必要欄位後等待精靈繼續；需要互動式新增時，請直接執行 cc-switch。

設定檔與安全

內容	預設路徑
CC Switch CLI 主資料庫	`~/.cc-switch/cc-switch.db`
CC Switch CLI 設定	`~/.cc-switch/settings.json`
自動備份	`~/.cc-switch/backups/`
Claude Code	`~/.claude/settings.json`
Codex	`~/.codex/config.toml`、`~/.codex/auth.json`
Gemini CLI	`~/.gemini/.env`、`~/.gemini/settings.json`
OpenCode	`~/.config/opencode/opencode.json`
Hermes	`~/.hermes/config.yaml`
OpenClaw	`~/.openclaw/openclaw.json`

Windows 中的 ~ 表示目前使用者目錄，通常是 %USERPROFILE%。可以執行 cc-switch config path 查看本機實際使用的設定路徑。

常見問題

切換後為什麼沒有生效

確認目標工具已執行過一次並建立設定目錄，然後檢查環境變數是否覆蓋了 CC Switch CLI 寫入的設定：

cc-switch env check --app claude
cc-switch env list --app claude

將 claude 替換為實際應用識別碼，再重新啟動終端和目標工具。

為什麼有些位址帶 /v1 有些不帶

Claude Code 和 Gemini CLI 會自行拼接協定路徑，所以使用站點根位址；Codex、OpenCode、Hermes 和 OpenClaw 接收 OpenAI 相容 Base URL，需要保留一個 /v1。

提示 401 或 API Key 無效

確認令牌複製完整、尚未過期、未被停用且有可用額度，同時檢查 IP 白名單等限制。建議從 TUI 重新輸入令牌，避免命令列跳脫或空格問題。

提示 404 或路徑不存在

檢查目標工具是否使用了正確位址，不要重複新增 /v1、/v1beta 或完整請求路徑。

提示模型不存在或不可用

返回 CoffeeRouter 令牌管理頁，複製目前令牌允許使用的模型 ID，並原樣填入 CC Switch CLI。不要使用顯示名稱或自行縮寫模型名稱。

CC Switch CLI 會轉發我的請求嗎

預設不會。它主要負責儲存和切換本機設定，目標 Agent 直接請求 CoffeeRouter。只有明確啟用 Claude、Codex 或 Gemini 的本機 Proxy 時，請求才會先經過本機 CC Switch CLI 代理；本教學不需要啟用該功能。