使用手冊

開源工具 · LLM 供應商切換 / Claude Code · Codex

在 macOS 一鍵切換 Claude Code、Codex 背後的 LLM。

farion1231/cc-switch 是 95.1k 星的跨平台桌面工具,一鍵切換 Claude Code、Codex 等 7 種 AI coding 工具的供應商。本手冊涵蓋 macOS 安裝、接上 MiniMax M3 / DeepSeek V4 Pro / OpenRouter owl-alpha,以及本地路由與自動容錯設定。

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,以及本地路由與自動容錯的建議配置。

farion1231/cc-switch
星標
86.3K
分支
5.6K
授權
—
資料截至
閱讀時間
9 分
更新日期
開啟原始報告
GitHub Stars
95.1k
支援的 AI 工具
7
供應商預設
50+
開源授權
MIT
本頁章節

01這是什麼

cc-switch 是 Claude Code 與 Codex 的供應商切換器。

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 需要重開終端機才會讀到新設定。

  1. 安裝

  2. 新增供應商

  3. 貼上金鑰

  4. 啟用切換

  5. 重開終端 / 熱重載

  6. 驗證模型

Claude Code 即時生效(支援熱重載);Codex 需要關閉並重新打開終端。

— cc-switch 官方使用手冊 · 快速開始

02macOS 安裝

用 Homebrew 一行安裝, 或下載 dmg。

需求是 macOS 12 以上。最簡單的方式是 Homebrew Cask。安裝完從 Launchpad 開啟 cc-switch,首次啟動會建立 ~/.cc-switch 資料夾與 SQLite 資料庫。它是 GUI 應用,日常切換在介面或 menu bar 圖示完成,不需要記指令。

bash
# 用 Homebrew 安裝
brew install --cask cc-switch

# 之後更新到最新版
brew upgrade --cask cc-switch

不用 Homebrew?下載 dmg

到 GitHub Releases 下載 CC-Switch-v3.16.2-macOS.dmg,拖進「應用程式」。首次開啟若被 Gatekeeper 攔下,到「系統設定 → 隱私權與安全性」按「仍要打開」。理解 cc-switch 改了哪些檔案,後續除錯會輕鬆很多——下面是它在背後讀寫的位置:

bash
# Claude Code:env 區塊的金鑰與端點
~/.claude/settings.json        # ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN

# Codex:模型與供應商設定 + 金鑰
~/.codex/config.toml           # model / model_provider / base_url / wire_api
~/.codex/auth.json             # OPENAI_API_KEY

# cc-switch 自身資料(供應商、MCP、prompt)
~/.cc-switch/cc-switch.db      # SQLite
~/.cc-switch/backups/          # 自動備份

03接上你的模型

把 MiniMax M3、DeepSeek、 OpenRouter 接進來。

新增供應商的欄位固定:名稱、Base URL、API Key、Model,外加備註與圖示。內建預設已填好 Base URL 與請求格式,接下面三個模型時,多數情況只要選預設、貼金鑰、填模型名稱。原則:Claude Code 走 Anthropic 相容端點,Codex 走 OpenAI 相容端點;Chat Completions 格式的上游(如 DeepSeek)由 cc-switch 的本地路由轉換,見第 04 節。每張卡片是一條設定路徑。

Claude Code · 01

MiniMax M3

Anthropic 相容

Claude Code 分頁 → 新增 → 選 MiniMax 預設(或自訂)→ 貼 API Key → Model 填供應商給的 M3 模型名(如 MiniMax-M3)→ 啟用。前提是 MiniMax 提供 Anthropic 相容端點;否則改走 Codex。

Claude Code · 02

DeepSeek V4 Pro

Anthropic 相容

Claude Code 分頁 → 選 DeepSeek 預設 → 貼金鑰 → Model 填 DeepSeek 文件的 V4 Pro 模型名 → 啟用。Claude Code 熱重載,開新對話即生效。

Codex · 03

DeepSeek V4 Pro

OpenAI Chat → 本地路由

Codex 分頁 → 選 DeepSeek 預設(會勾「需要本地路由映射」)→ 貼金鑰 → 在設定開啟本地路由 → 啟用 → 重開 Codex 終端。DeepSeek 只給 Chat 格式,由路由轉成 Responses。

Claude Code · 04

openrouter/owl-alpha

OpenRouter 預設

Claude Code 分頁 → 選 OpenRouter 預設 → 貼 OpenRouter 金鑰 → Model 填 owl-alpha 的模型 slug → 啟用。預設已帶 OpenRouter 端點與格式。

Codex · 05

openrouter/owl-alpha

OpenAI 相容

Codex 分頁 → 選 OpenRouter 預設 → 貼金鑰 → Model 填 slug → 重開終端。OpenRouter 走 OpenAI 格式,Codex 可直接接,或在需要時經本地路由。

自訂 · 06

Custom Provider

任意端點

沒有對應預設時用自訂:填 Name、Base URL、API Key、Model。記住端點格式要對:Claude Code 需 Anthropic 相容,Codex 需 OpenAI 相容。

生效 · 07

熱重載 vs 重開

切換行為

Claude Code 即時生效;Codex / Gemini / OpenCode / OpenClaw 需關閉並重開終端。設定檔在切換當下已更新,但執行中的程式不會自動重讀。

驗證 · 08

/model

Codex 確認

重開 Codex 後輸入 /model,確認顯示的供應商與模型和你選的一致。Claude Code 則看新對話的回應來源。

金鑰 · 09

auth.json / settings.json

存放位置

Codex 金鑰寫 ~/.codex/auth.json;Claude Code 金鑰寫 ~/.claude/settings.json 的 env。cc-switch 統一管理,不必手改檔案。

哪個工具走哪種端點

工具端點格式切換後生效方式
Claude CodeAnthropic 相容(ANTHROPIC_BASE_URL)熱重載,即時
CodexOpenAI 相容 / Responses(必要時本地路由)重開終端
Gemini CLIGemini(GEMINI_API_KEY)重開終端
OpenCode / OpenClawOpenAI 相容重開終端

04建議配置 · 進階

跑 agent coding 的推薦設定。

下面幾條來自 cc-switch 官方文件記載的功能,是社群討論換模型時最常用到的設定。重點是把多個供應商接成一條有容錯的路徑,而不是每次手動換金鑰。agent 的長任務一旦中途斷線或撞額度,整段 context 容易作廢,所以路由與容錯比「換哪個模型」更值得先設好。

本地路由:讓 Codex 用上 Chat 格式模型

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。

來源 · cc-switch 官方文件 · Codex-DeepSeek 路由指南

自動容錯:主供應商掛了自動切備援

本地路由支援 auto-failover 與斷路器(circuit breaker)。把多個供應商排成一條鏈,主端點失敗時自動切到下一個,避免 agent 長任務跑到一半因為 429 / 5xx 整段中斷。

來源 · cc-switch README · 本地代理段落

切換前用 Model Test 驗端點

先在「模型測試」頁打一次,確認金鑰、端點、模型名稱三者對得上,再讓 Claude Code / Codex 接手。省去 agent 跑到一半才回 401 / 404 才發現設定錯。

來源 · cc-switch 使用手冊 · 4.5 模型測試

MCP 跨工具同步,設一次共用

cc-switch 統一管理 MCP server,可雙向同步到各工具。一次設好,Claude Code 與 Codex 共用同一組 MCP,不必各自貼設定,換供應商時也不會漏掉工具連線。

來源 · cc-switch README · MCP 管理

menu bar 快切,兩下換模型

從系統列(menu bar)圖示右鍵直接點供應商名稱即可切換,不必開主視窗。配合 Claude Code 熱重載,換一個後端模型只要兩下,適合在便宜模型與強模型之間頻繁來回。

來源 · cc-switch 使用手冊 · 快速開始

雲端同步,多台 Mac 同一套設定

透過 iCloud / Dropbox / OneDrive / WebDAV 同步 ~/.cc-switch,換機或多台 Mac 共用同一組供應商與金鑰配置。注意這等於把金鑰一起上雲,先確認該帳號安全。

來源 · cc-switch README · 雲端同步

05實作示範

把 Codex 從 OpenAI 切到 DeepSeek V4 Pro。

以下示範把 Codex 的後端從 OpenAI 換成 DeepSeek V4 Pro,走 cc-switch 本地路由,再用 /model 驗證;最後順手把 Claude Code 熱切到 MiniMax M3。GUI 的點選步驟以註解標示,終端只顯示安裝與驗證指令。

~/projects/api · codex · cc-switch v3.16.2


# 1 · 安裝 cc-switch(Homebrew)
$ brew install --cask cc-switch
# ==> Installing Cask cc-switch
ok: 🍺  cc-switch was successfully installed!


# 2 · GUI:Codex 分頁 → + → 選 DeepSeek 預設 → 貼 API Key
# 3 · 設定 → 路由 → 本地路由:開主開關(127.0.0.1:15721)、勾選 Codex
#     cc-switch 已改寫 ~/.codex/config.toml:
  hl: base_url = "http://127.0.0.1:15721/v1"
  hl: wire_api = "responses"
# 4 · 在卡片按「啟用」DeepSeek,然後重開 Codex 終端


$ codex
$ /model
  provider : deepseek (via cc-switch 127.0.0.1:15721)
  model    : DeepSeek V4 Pro
ok: ✓ 後端已切換,專案設定一行沒改


# 5 · 順手把 Claude Code 後端換成 MiniMax M3
#     cc-switch → Claude Code 分頁 → MiniMax → 啟用
#     Claude Code 熱重載,開新對話即生效:
  hl: ~/.claude/settings.json · env.ANTHROPIC_BASE_URL 已更新
ok: ✓ 不必重開終端,下一則訊息就走 MiniMax M3

配置文件在切換時已經更新, 但執行中的程式不會自動重新載入。

— cc-switch 使用手冊。這就是 Codex 要重開終端、Claude Code 不用的原因

為什麼 Codex 需要本地路由

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 後端要多開一個本地路由、並重開終端。理解這個差異,就不會在「切了沒反應」時白白除錯。

06先看清楚這些

切供應商前, 知道這些邊界。

07進階路徑

把 cc-switch 當成你的供應商路由層。

把 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。

切供應商只是把 Claude Code 與 Codex 的後端換掉; agent 的成敗,仍取決於你選的模型與流程。

— cc-switch 把切換變簡單,判斷仍在你手上