cc-switch 是用 Rust + Tauri 寫的跨平台桌面工具,管理 Claude Code、Codex、Gemini CLI 等 7 種 AI coding 工具的供應商設定。它把分散在 ~/.claude/settings.json、~/.codex/config.toml 的金鑰與端點集中成圖形介面,切換變成點一下。本手冊涵蓋 macOS 安裝、接上 MiniMax M3、DeepSeek V4 Pro、OpenRouter owl-alpha,以及本地路由與自動容錯的建議配置。
cc-switch 由開發者 farion1231 維護,GitHub 95.1k 星、MIT 授權,以 Rust 與 Tauri 2 建置。它解決一個具體問題:Claude Code、Codex、Gemini CLI 各自把 API 金鑰與端點寫在不同設定檔,要換一個 LLM 供應商,得手動編輯 JSON 或 TOML。cc-switch 把這些設定收進一個桌面應用,切換供應商變成點一下。官方網站是 ccswitch.io。
運作方式是直接改寫各工具的設定檔。切到某個供應商時,cc-switch 會把對應金鑰與端點寫進該工具的設定:Claude Code 寫 ~/.claude/settings.json 的 env 區塊(ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN);Codex 寫 ~/.codex/auth.json 與 ~/.codex/config.toml。所有供應商、MCP、prompt 資料存在 ~/.cc-switch/cc-switch.db(SQLite)。
它支援 7 種工具:Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes Agent。內建 50+ 供應商預設,預設已填好端點與請求格式,接第三方模型時多數情況只需貼上金鑰、填模型名稱。一個關鍵差異:切換後 Claude Code 即時熱重載,Codex 與其他 CLI 需要重開終端機才會讀到新設定。
需求是 macOS 12 以上。最簡單的方式是 Homebrew Cask。安裝完從 Launchpad 開啟 cc-switch,首次啟動會建立 ~/.cc-switch 資料夾與 SQLite 資料庫。它是 GUI 應用,日常切換在介面或 menu bar 圖示完成,不需要記指令。
到 GitHub Releases 下載 CC-Switch-v3.16.2-macOS.dmg,拖進「應用程式」。首次開啟若被 Gatekeeper 攔下,到「系統設定 → 隱私權與安全性」按「仍要打開」。理解 cc-switch 改了哪些檔案,後續除錯會輕鬆很多——下面是它在背後讀寫的位置:
~/.claude/settings.json 與 ~/.codex/;cc-switch 本身也會在 ~/.cc-switch/backups/ 保留備份。Claude Code 官方 OAuth 登入與第三方金鑰可並存;Codex 另有「官方登入保留」機制,避免切換時覆蓋 auth.json。
新增供應商的欄位固定:名稱、Base URL、API Key、Model,外加備註與圖示。內建預設已填好 Base URL 與請求格式,接下面三個模型時,多數情況只要選預設、貼金鑰、填模型名稱。原則:Claude Code 走 Anthropic 相容端點,Codex 走 OpenAI 相容端點;Chat Completions 格式的上游(如 DeepSeek)由 cc-switch 的本地路由轉換,見第 04 節。每張卡片是一條設定路徑。
/model,確認顯示的供應商與模型和你選的一致。Claude Code 則看新對話的回應來源。~/.codex/auth.json;Claude Code 金鑰寫 ~/.claude/settings.json 的 env。cc-switch 統一管理,不必手改檔案。| 工具 | 端點格式 | 切換後生效方式 |
|---|---|---|
| Claude Code | Anthropic 相容(ANTHROPIC_BASE_URL) |
熱重載,即時 |
| Codex | OpenAI 相容 / Responses(必要時本地路由) | 重開終端 |
| Gemini CLI | Gemini(GEMINI_API_KEY) |
重開終端 |
| OpenCode / OpenClaw | OpenAI 相容 | 重開終端 |
下面幾條來自 cc-switch 官方文件記載的功能,是社群討論換模型時最常用到的設定。重點是把多個供應商接成一條有容錯的路徑,而不是每次手動換金鑰。agent 的長任務一旦中途斷線或撞額度,整段 context 容易作廢,所以路由與容錯比「換哪個模型」更值得先設好。
Codex 預期 Responses API,DeepSeek 等只給 Chat Completions。到「設定 → 路由 → 本地路由」開啟主開關(預設 127.0.0.1:15721),cc-switch 會把 Codex 的 base_url 改寫成 http://127.0.0.1:15721/v1,並把 Responses 請求轉成 Chat。
本地路由支援 auto-failover 與斷路器(circuit breaker)。把多個供應商排成一條鏈,主端點失敗時自動切到下一個,避免 agent 長任務跑到一半因為 429 / 5xx 整段中斷。
來源 · cc-switch README · 本地代理段落先在「模型測試」頁打一次,確認金鑰、端點、模型名稱三者對得上,再讓 Claude Code / Codex 接手。省去 agent 跑到一半才回 401 / 404 才發現設定錯。
來源 · cc-switch 使用手冊 · 4.5 模型測試cc-switch 統一管理 MCP server,可雙向同步到各工具。一次設好,Claude Code 與 Codex 共用同一組 MCP,不必各自貼設定,換供應商時也不會漏掉工具連線。
來源 · cc-switch README · MCP 管理從系統列(menu bar)圖示右鍵直接點供應商名稱即可切換,不必開主視窗。配合 Claude Code 熱重載,換一個後端模型只要兩下,適合在便宜模型與強模型之間頻繁來回。
來源 · cc-switch 使用手冊 · 快速開始透過 iCloud / Dropbox / OneDrive / WebDAV 同步 ~/.cc-switch,換機或多台 Mac 共用同一組供應商與金鑰配置。注意這等於把金鑰一起上雲,先確認該帳號安全。
以下示範把 Codex 的後端從 OpenAI 換成 DeepSeek V4 Pro,走 cc-switch 本地路由,再用 /model 驗證;最後順手把 Claude Code 熱切到 MiniMax M3。GUI 的點選步驟以註解標示,終端只顯示安裝與驗證指令。
Codex 預期 Responses API,而 DeepSeek 這類模型多半只提供 Chat Completions。cc-switch 的本地代理在 127.0.0.1:15721 把兩種協定互轉:把 Codex 發出的 Responses 請求改寫成 Chat,再把回應轉回 Responses。所以 Codex 以為自己在跟 OpenAI 講話,實際後端是 DeepSeek。
Claude Code 不需要這層轉換,因為它直接走 Anthropic 相容端點,而且支援熱重載。換句話說:切 Claude Code 後端是兩下點選即生效;切 Codex 後端要多開一個本地路由、並重開終端。理解這個差異,就不會在「切了沒反應」時白白除錯。
~/.claude/settings.json、~/.codex/auth.json 與 ~/.cc-switch 資料庫。共用電腦或上傳 dotfiles 時,注意別把金鑰一起外洩。
~/.cc-switch 等於把金鑰一起上雲。先確認該雲端帳號本身夠安全,再開同步。
auth.json 被洗掉。詳見 docs/guides 的 codex-official-auth-preservation 指南。
把 cc-switch 從「換金鑰的工具」升級成一條有容錯的供應商路徑後,換模型這件事就不再打斷 agent 的工作。下面五條按投資報酬率排序。
1. 設好容錯鏈。主用便宜或快的模型(owl-alpha / DeepSeek),備援放官方 Claude / OpenAI,在本地路由開 auto-failover。主端點掛掉時自動切備援,長任務不中斷。
2. 用 MCP 同步一次到位。在 cc-switch 設好 MCP server,雙向同步給 Claude Code 與 Codex。換供應商時工具連線不會掉。
3. 用 prompt 管理同步記憶檔。cc-switch 的 prompt 管理可把同一份內容寫進 CLAUDE.md、AGENTS.md、GEMINI.md,各工具共用同一套規則。
4. 跨機同步配置。用 WebDAV / iCloud 同步 ~/.cc-switch,多台 Mac 共用同一組供應商、MCP 與 prompt。
5. 讀官方指南再上生產。docs/guides 有 Codex-DeepSeek 路由、Codex 官方登入保留、proxy 三份指南,涵蓋多數會踩到的細節。
① ccswitch.io——官方網站與下載入口。
② github.com/farion1231/cc-switch——README 與 CHANGELOG,功能以此為準。
③ docs/user-manual——多語使用手冊,含供應商、代理、路由、FAQ。