AI工具

CC Switch 使用教程：安全管理 Claude Code、Codex、MCP 與配置回滾

依據 CC Switch 官方倉庫，說明可信下載渠道、Provider 切換、設定目錄、自動備份、Codex 協議轉換、故障驗證和回滾方法。

CC Switch，也常被搜尋為 CCSwitch 或 cc switch，是一個面向 AI 程式設計重度使用者的桌面管理工具。它要解決的問題很直接：現在很多人同時使用 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw，但每個工具都有自己的配置格式、Provider 寫法、MCP 配置和 Skills 管理方式。

當你只用一個工具時，手動改配置還能忍；一旦多個工具混用，再加上官方賬號、第三方 API、中轉服務、本地模型和團隊共享配置，手動編輯 JSON、TOML、.env 很快就會變成一件很煩的事。

CC Switch 的定位，就是把這些分散配置收進一個跨平臺桌面應用裡。 它解決什麼問題

現代 AI 程式設計工具越來越像“命令列裡的開發同事”，但每個工具的生態還沒有完全統一。

常見痛點包括：

  • Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 配置格式不同。
  • 切換 API Provider 時，要反覆改配置檔案。
  • MCP server 在不同工具之間重複配置。
  • CLAUDE.md、AGENTS.md、GEMINI.md 這類提示檔案難以統一維護。
  • Skills 安裝、同步、備份和解除安裝缺少一個集中入口。
  • 多個賬號、多個 relay、多個模型服務切換很容易搞混。
  • 配置檔案手工修改出錯後，排查成本很高。

CC Switch 的思路是：不要讓使用者記住每個工具的配置細節，而是用一個統一介面管理 Provider、MCP、Prompts、Skills、Sessions 和代理。 支援哪些工具

README 中列出的核心支援物件包括五類：

  • Claude Code
  • Codex
  • Gemini CLI
  • OpenCode
  • OpenClaw

這幾個工具本身定位相近，都是圍繞 AI 程式設計、Agent 工作流和命令列協作展開。但它們的配置體系不同，CC Switch 的價值就在於把這些差異包裝起來。

對經常比較不同 AI 程式設計工具的人來說，這比每次手動翻配置檔案省心很多。 Provider 管理

CC Switch 的第一層能力是 Provider 管理。

它內建了 50 多個 Provider 預設，README 中提到的方向包括 AWS Bedrock、NVIDIA NIM，以及各種社群 relay。使用者可以複製 API key，一鍵匯入，然後在介面中切換。

實用點主要有幾個：

  • 一鍵新增 Provider。
  • Provider 拖拽排序。
  • 系統托盤快速切換。
  • Provider 匯入和匯出。
  • 部分通用 Provider 可同步到多個應用。

對很多人來說，這個功能已經足夠有吸引力。因為 AI 程式設計工具的日常使用，經常不是“模型不會用”，而是“今天這個 key 用哪個工具、哪個 endpoint、哪個賬號”容易亂。 本地代理與故障切換

除了寫配置檔案，CC Switch 還提供本地代理模式。

這個能力的重點是：

  • 熱切換 Provider。
  • 格式轉換。
  • 自動故障轉移。
  • 熔斷器。
  • Provider 健康檢查。
  • 請求修正。

簡單說，它不只是把配置寫進目標工具，還可以在中間加一層本地代理，讓不同工具透過代理訪問模型服務。

這對多 Provider 使用者很有用：一個服務掛了，可以切到另一個；一個模型貴，可以換成更便宜的；某個請求格式不相容，也可以透過代理層做適配。 MCP、Prompts 和 Skills

CC Switch 比較重要的第二層能力，是統一管理 MCP、Prompts 和 Skills。 MCP

它提供統一 MCP 面板，可以在多個應用之間管理 MCP server，並支援雙向同步和 Deep Link 匯入。

這對正在用 MCP 的使用者很實用。因為 MCP server 一多，配置很容易分散在不同客戶端裡。統一面板可以減少重複配置，也方便遷移。 Prompts

Prompts 部分支援 Markdown 編輯，並且可以在不同工具之間同步對應檔案，例如：

  • CLAUDE.md
  • AGENTS.md
  • GEMINI.md

這些檔案本質上都是給 Agent 的專案說明書。統一管理後，可以更容易維護團隊規則、專案約定和全域性提示。 Skills

Skills 支援從 GitHub 倉庫或 ZIP 檔案一鍵安裝，也支援自定義倉庫管理、符號連結和檔案複製。

如果你同時使用 Claude Code、Codex、OpenClaw 這類工具，Skills 很容易變成一堆散落在不同目錄的檔案。CC Switch 把它們集中起來，能降低維護成本。 會話與工作區

README 還提到 Session Manager 和 Workspace 相關能力。

它可以瀏覽、搜尋和恢復多個應用裡的會話歷史。對長期使用 AI 程式設計工具的人來說，會話管理其實很重要：很多有價值的上下文、除錯過程、方案比較，都埋在舊對話裡。

此外，它還為 OpenClaw 提供 Workspace editor，可以編輯 AGENTS.md、SOUL.md 等 agent 檔案，並帶 Markdown 預覽。

這說明 CC Switch 不只是一個“切換 key 的小工具”，而是在往 AI Agent 工作臺方向擴充套件。 雲同步與資料儲存

CC Switch 支援透過 Dropbox、OneDrive、iCloud、NAS 或 WebDAV 同步 Provider 資料。

本地資料儲存方式也比較清楚：

  • 資料庫：~/.cc-switch/cc-switch.db
  • 本地設定：~/.cc-switch/settings.json
  • 自動備份：~/.cc-switch/backups/
  • Skills：~/.cc-switch/skills/
  • Skill 備份：~/.cc-switch/skill-backups/

它使用 SQLite 作為主要資料來源，並強調原子寫入和自動備份，目標是避免配置檔案在切換或寫入時損壞。

這個設計對重度使用者很關鍵。因為一旦配置管理工具本身把配置寫壞，影響的是所有 AI 程式設計工具。 安裝方式

CC Switch 是跨平臺桌面應用，基於 Tauri 2 構建。

系統要求大致如下：

  • Windows：Windows 10 及以上
  • macOS：macOS 12 Monterey 及以上
  • Linux：Ubuntu 22.04+、Debian 11+、Fedora 34+ 等主流發行版

Windows 使用者可以下載 .msi 安裝包或便攜版壓縮包。

macOS 使用者可以用 Homebrew：

1
2

brew tap farion1231/ccswitch
brew install --cask cc-switch

更新：

1

brew upgrade --cask cc-switch

Linux 使用者可以選擇 .deb、.rpm 或 AppImage。Arch Linux 使用者也可以透過 paru -S cc-switch-bin 安裝。

截至 2026 年 5 月 6 日，倉庫頁面顯示最新 release 為 CC Switch v3.14.1，釋出時間是 2026 年 4 月 23 日。 技術棧

從倉庫結構看，CC Switch 是典型的 Tauri 桌面應用：

  • 前端：React 18、TypeScript、Vite、TailwindCSS、TanStack Query、shadcn/ui
  • 後端：Tauri 2、Rust、SQLite、Tokio
  • 測試：Vitest、MSW、Testing Library

核心設計模式包括：

  • SQLite 作為 Single Source of Truth。
  • JSON 儲存裝置級本地設定。
  • 切換時寫入目標工具的 live config。
  • 編輯當前 Provider 時從 live config 回填。
  • 使用臨時檔案加 rename 的方式做原子寫入。
  • 資料庫連線加鎖，避免併發寫入問題。

這類架構說明專案並不是簡單指令碼，而是按長期桌面工具來設計的。 適合誰用

CC Switch 適合下面幾類使用者：

  • 同時使用 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw。
  • 經常切換官方賬號、第三方 relay、本地模型或團隊 Provider。
  • 已經開始大量使用 MCP。
  • 想統一維護 CLAUDE.md、AGENTS.md、GEMINI.md。
  • 經常安裝、測試和遷移 Skills。
  • 想看不同工具的會話歷史和使用情況。

如果你只用一個 AI 程式設計工具，而且一直走官方登入，不怎麼折騰 Provider、MCP 和 Skills，那它的價值可能沒那麼明顯。

但如果你已經進入“多工具、多賬號、多 Provider、多專案”的狀態，它能省掉很多瑣碎配置工作。 需要注意什麼

這類工具很方便，但也要注意邊界。

第一，它會管理多個 AI CLI 的配置，因此要確認自己信任這個工具和它的寫入邏輯。

第二，API key、relay endpoint、MCP server 都屬於敏感配置。開啟雲同步前，要確認同步目錄和 WebDAV 服務本身安全可靠。

第三，切換 Provider 後，多數工具仍然需要重啟終端或 CLI 才能生效。README 中提到，Claude Code 對 Provider 資料支援熱切換，但其他工具通常仍需要重啟。

第四，切回官方登入時，最好按專案說明新增 official provider，再重新走對應工具的登入流程。 安裝前先核對官方渠道

專案當前宣告的官方來源只有：

  • 官網：ccswitch.io
  • 原始碼：github.com/farion1231/cc-switch
  • 下載：該 GitHub 倉庫的 Releases

CC Switch 是免費開源軟體。要求充值、索取官方賬號密碼或冒用名稱的下載站不應使用。Windows 優先下載 Releases 中的 MSI；macOS 可以使用：

1

brew install --cask cc-switch

安裝後在“關於”或工具管理介面核對已安裝版本，不要根據第三方教程裡的舊版本號下載固定檔案。 修改前備份哪些檔案

CC Switch 官方 README 當前列出的本地資料位置是：

1
2
3
4
5

数据库：~/.cc-switch/cc-switch.db
设置：~/.cc-switch/settings.json
自动备份：~/.cc-switch/backups/
Skills：~/.cc-switch/skills/
Skill 备份：~/.cc-switch/skill-backups/

backups 預設輪換保留最近 10 份，Skills 解除安裝前的備份保留最近 20 份。自動備份不等於完整災難恢復；第一次大規模切換前，應退出 CC Switch，再把整個 ~/.cc-switch 目錄複製到受控位置。

同時單獨儲存目標工具原有配置，例如使用者目錄下的 Codex config.toml。不要把包含 API Key 的備份提交到 Git 或上傳到公開網盤。 一次安全的 Provider 切換

  1. 在原 CLI 中執行一個最小請求，儲存正常基線。
  2. 在 CC Switch 中新增 Provider，不覆蓋唯一可用的官方 Provider。
  3. 檢查 endpoint、模型名和 Key 對應的環境變數。
  4. 切換後完全退出並重啟目標 CLI。
  5. 先測試普通文字，再測試流式響應和工具呼叫。
  6. 出現異常時切回原 Provider，並確認原 CLI 恢復。

Codex 原生自定義 Provider 使用 Responses 協議。CC Switch 3.16 起的本地代理可以把 Codex 的 Responses 請求轉換為部分第三方供應商使用的 Chat Completions，並重建流式響應和工具呼叫。是否能穩定工作仍取決於具體版本、上游模型和代理配置，不能因為聊天返回一句文字就認為 Codex 工作流全部相容。 驗證和故障定位

切換 Codex Provider 後，至少執行：

1
2

codex --version
codex --help

隨後在一個臨時 Git 倉庫中完成三項測試：

  • 讀取檔案並回答問題；
  • 修改一個測試檔案並檢視 diff；
  • 呼叫一個無副作用工具。

常見判斷：

現象 優先檢查
401 Key、環境變數、認證頭
404 base URL、端點路徑、模型 ID
能聊天但工具失敗 Responses/Chat 協議轉換與工具呼叫格式
切換後仍走舊 Provider CLI 是否重啟、設定目錄是否一致
codex resume 找不到會話 會話記錄的 model_provider 分組

CC Switch README 特別說明：它預設以應用設定中的 Codex 目錄為準，並不會自動讀取 CODEX_HOME。如果 CLI 使用了自定義目錄，應在 CC Switch 中設定相同的“配置檔案目錄”。 回滾步驟

  1. 在 CC Switch 中切回之前保留的官方或已驗證 Provider。
  2. 退出 CC Switch 和目標 CLI。
  3. 從 ~/.cc-switch/backups/ 選擇修改前備份；不確定時不要覆蓋資料庫。
  4. 必要時恢復單獨儲存的 config.toml。
  5. 重新登入官方 Provider，並重跑最小基線請求。

CC Switch 的“最小侵入”設計會保留一個活動配置，因此不能刪除當前唯一活動 Provider。正確做法是先切換到可用 Provider，再清理錯誤配置。 安全邊界

  • 不使用來歷不明的 relay 或收費映象站。
  • 不在截圖、日誌和同步目錄中洩露 API Key。
  • 使用 WebDAV 同步前確認服務端加密、權限和資料留存政策。
  • 使用第三方 Provider 前閱讀其計費、資料留存和服務條款。

- 不用 ChatGPT 訂閱 OAuth 反向代理規避正常授權路徑；專案釋出說明也提示這可能違反 OpenAI 服務條款。 小結

CC Switch 的價值不在於又做了一個 AI 程式設計工具，而在於它承認了一個現實：AI 程式設計生態已經進入多工具並存階段。

Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 各有自己的配置系統，MCP、Skills、Prompts、Provider 又在快速擴充套件。繼續靠手動改配置，遲早會變成負擔。

CC Switch 把這些東西收進一個桌面應用裡，讓使用者可以更輕鬆地切換 Provider、同步 MCP、管理 Skills、維護提示檔案和檢視會話。對重度 AI 程式設計使用者來說，這類工具很可能會從“可選小工具”變成“日常基礎設施”。 常見問題

CC Switch 和 CCSwitch 是同一個工具嗎？

是。使用者搜尋時可能會寫成 CC Switch、CCSwitch 或 cc switch，這裡討論的是 farion1231/cc-switch 這個跨平臺桌面工具。 CC Switch 能管理哪些 AI 程式設計工具？

它主要面向 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 這類 AI CLI 和 Agent 工具，重點管理 Provider、MCP、Prompts、Skills、代理和會話。 CC Switch 是隻用來切換 API Key 嗎？

不只是。切換 Provider 是它的基礎能力，但它還在往 AI Agent 工作臺方向擴充套件，包括 MCP 管理、Skills 同步、提示檔案維護、會話檢視和雲同步。 什麼情況下最值得安裝 CC Switch？

如果你同時使用多套 AI 程式設計工具、多組 API Provider、本地模型、relay 或團隊共享配置，CC Switch 可以明顯減少手工改配置的成本。 參考資料

用 Ollama 建立本機模型 Provider

先在與 CC Switch、Claude Code 相同的使用者環境確認 Ollama 服務與完整模型標籤：

1
2

ollama list
Invoke-RestMethod -Uri 'http://127.0.0.1:11434/api/tags'

在 CC Switch 新增 Ollama Local Provider，Base URL 填 http://127.0.0.1:11434/v1，協定選 OpenAI-compatible / Chat Completions，模型名稱逐字使用 ollama list 的標籤。若表單強制要求 API Key，填本機占位字串即可，不要放入真實雲端金鑰。

切換前先備份原 Provider，並在唯讀倉庫驗證一般回覆、讀檔 tool call、取消請求後恢復三項。只有對話成功不代表完整 Claude Code Agent 流程相容；本機模型若 tool calling 不穩或輸出格式不符，應換模型、嘗試 CC Switch 協定轉換，或立即回復原 Provider。

CLI 正常但 API 不通時，檢查 Ollama 是否位於 Windows/WSL 的另一側、11434 是否監聽，以及防火牆。端點能列出模型卻顯示 “model not found”，通常是模型標籤不完整。不要把未驗證的 11434 直接暴露到網際網路。