CC Switch 使用指南：统一管理 10 个 AI 编程工具的提供商、MCP 与上下文

学习目标

通过本文，你应该能够：

• 说清 CC Switch 的定位：它不是什么、它是什么、它解决的核心问题是什么
• 判断你自己是否需要 CC Switch（什么场景下值得装、什么场景下不需要）
• 区分 Switch 与 Coexist 两种接入模式，理解各自的生效时机
• 完成安装和首次配置，理解"接管边界"以避免常见误解
• 理解 Local Routing 的真实能力边界，不夸大也不低估
• 配置多设备同步，理解它的同步范围和不覆盖的场景

评估 CC Switch 时，先抓住四个判断

• 它管理的工具已经从年初的 6 个扩展到 10 个，但各工具拿到的是"统一界面"，不是完全一致的底层实现。
• 它解决的是"配置与上下文管理"问题，不替代任何 CLI 的推理能力，也不提供模型服务。
• 切换是否立即生效取决于工具：Claude Code 可以热切换，Codex 这类工具要重开终端，还有一批工具走"多提供商共存"路线。
• 如果你只用单一 CLI 和单一官方 API，它暂时给不了你决定性收益。

CC Switch 本质上是什么

CC Switch 不是 Claude Code、Codex 或 OpenClaw 的替代品，也不是新的模型服务；它是一层位于这些 CLI 之外的管理平面，负责把原本分散在多个目录、多个配置格式里的内容收拢起来。官方仓库对它的定位是一句话：All-in-One Manager（全功能管理器）。

它解决的核心问题可以归为两类：

1. 提供商切换：同一套工作流里，开发者往往会在官方 API、中转服务、自建网关和不同地区节点之间切换。
2. 上下文资产管理：MCP、Skills、Prompts、会话和部分工作区配置，本质上都属于"让 agent 更会做事"的外围资产，但它们通常散落在不同工具的不同目录里。

项目 2025 年 8 月上线，截至 2026 年 9 月下旬，GitHub Star 已超过 13.8 万，当前版本 v3.20.4。Star 数字说明需求旺盛，但比 Star 更重要的是：CC Switch 把"多 CLI 共存"从手工维护配置，提升到了可视化管理。

当前支持的 10 个工具

CC Switch 的支持范围在 2026 年扩张得很快：v3.14.0（4 月）把 Hermes Agent 纳入为第 6 个受管应用，v3.15.0（5 月）加入 Claude Desktop，v3.18.0（7 月）加入 xAI 的 Grok Build，v3.20.0（8 月）加入 Pi，v3.20.4（9 月）加入 MiniMax Code。如果你看到的资料还在写"6 个工具"或"8 个工具"，那是几个月前的旧信息。

这张表也提示了一个现实问题：CC Switch 做的是"统一管理"，不是把所有工具磨成完全一样。Claude Code 的体验最完整，而 OpenClaw 没有接入 MCP 和 Skills 同步，Pi 没有原生 MCP 注册表所以被刻意排除在 MCP 同步之外。引入前值得对照这张表，确认你在乎的能力对你的工具是否成立。

两种接入模式：Switch 与 Coexist

理解这张表的关键，是官方对工具的两分法：

• Switch（切换式）：一次只有一个 provider 生效。切换时，CC Switch 改写该工具自己的配置文件。Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build 属于这一类。
• Coexist（共存式）：多个 provider 同时写入工具自己的配置，你在工具内部选择用哪个。OpenCode、OpenClaw、Hermes Agent、Pi、MiniMax Code 属于这一类——点一次按钮就是往工具的配置里多写一个可选节点（OpenCode、OpenClaw、Hermes Agent 和 MiniMax Code 的按钮叫"添加"，Pi 叫"启用"）。

生效时机也随模式不同。切换 provider 之后：

• Claude Code 支持热切换，无需重启；
• Codex、Gemini CLI、Grok Build 需要重开终端会话（CC Switch 会在切换后提醒你）；如果开了本地路由，请求立即走向新 provider，但模型变了仍可能要重启；
• Claude Desktop 需要完全退出再打开；
• Coexist 类工具的写入即时生效，最终用哪个模型由你在工具里自己挑。

这套差异不是 CC Switch 的缺陷，而是各 CLI 配置加载机制不同——它选择如实呈现，而不是假装抹平。

它解决的，不只是切换账号

把重点放在"一键切换 provider"上，只看到了入口。它更值钱的部分在下面三层。

把提供商切换从手改配置文件变成统一操作

不同 CLI 的配置格式并不一致，有的是 JSON，有的是 TOML、YAML 或 .env。每换一次提供商，你可能都要去不同目录修改不同字段。CC Switch 把这件事收敛成同一套操作：从 90 多个内置预设（覆盖 AWS Bedrock、NVIDIA NIM 和各类社区中转）里挑一个，填入密钥，点击启用；没有预设的服务也可以自定义录入。

切换动作是"最小侵入"的：只替换端点、密钥、模型名这些关键字段，你自己在配置文件里加的插件、hooks、MCP、环境变量、注释全都原样保留。首次改写某个工具的配置文件之前，原始文件会先备份到 ~/.cc-switch/backups/live-first-write/，所以"被接管"不等于"被覆盖丢失"。

在 provider 之上，它还提供两个组织手段：Projects 可以把 Claude Code 或 Codex 当前的 provider、MCP、Skills 和 prompt 文件保存成一组快照，之后从主页顶部或托盘一键切换整套配置；OAuth 认证中心（Beta） 支持登录多个 GitHub Copilot、ChatGPT 和 xAI（Grok）账号，把这些订阅当作 provider 使用——官方明确提醒，在非官方客户端里使用订阅可能违反服务商条款，风险自担。

把 MCP、Skills、Prompts 和 Memory 视为同一类资产来管理

对 AI 编程 CLI 来说，决定体验上限的往往不是界面，而是上下文资产能否复用。CC Switch 在这方面的投入比"切 provider"更彻底：

这里最容易说错的是 Hermes Agent。它不使用传统的 Prompts 面板，而是用 Memory 面板管理类似 MEMORY.md、USER.md 这样的内容。如果你希望一套 Prompts 工作流无差别覆盖所有应用，需要先接受一个事实：CC Switch 提供的是统一管理界面，不是完全同构的底层实现。

把"切换之后会发生什么"也纳入管理

很多工具到"改完配置"就结束了，但切换之后的体验同样影响日常效率：

• 系统托盘：Claude Code、Codex、Gemini CLI、Grok Build 四个 Switch 式工具支持托盘直接切换，还能显示当前 provider 的订阅额度与用量徽标。
• 会话管理：浏览、搜索各工具的历史会话，复制恢复命令继续对话；macOS 上可以一键在终端恢复。OpenClaw 和 Hermes Agent 的会话目前只读，暂不支持恢复。
• 工作区编辑：OpenClaw 的工作区编辑器可以直接维护 AGENTS.md、SOUL.md 这类 agent 文件和每日记忆，这是它的差异化能力。
• 用量与成本：不开本地路由也能统计——默认扫描各工具的本地会话日志，按 provider 和模型汇总请求数、token、缓存命中率和花费；provider 卡片上还能显示官方订阅配额和账户余额（部分需要手动开启），价格表支持自定义，也可以从 models.dev 导入。

Local Routing 是它的另一条主线

如果只把 CC Switch 当成"配置编辑器"，会错过它最有工程含量的部分。Local Routing 在本机替你的 CLI 接收请求，做两件事：协议转换和故障转移。

协议转换解决一个具体矛盾：Claude Code 只说 Anthropic 协议，但你想给它接一家只有 OpenAI 接口的中转，或者反过来在 Codex 里用 Claude 系的 provider。开启路由后，它在本机把 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 和 Gemini Native 四种格式互转，任何一边接任何一边都成立。

开启方式是按工具独立的：在"设置 → 路由 → 本地路由"里打开总开关，再为需要的工具打开路由。之后该工具的配置文件会被改写为指向本机（默认 http://127.0.0.1:15721），密钥字段变成占位符 PROXY_MANAGED——真正的地址、密钥和模型都存在 CC Switch 里。请求日志（“设置 → 用量统计 → 请求日志”）能看到每个请求"请求的模型 → 实际模型"的映射。

故障转移为每个工具配置一个 provider 队列：请求失败时自动切到队列里的下一个，背后有熔断器和 provider 健康监测兜底。另有一个 Rectifier 机制，自动修正某些上游处理不了的请求，比如 Thinking 签名、图片不支持时的回退。

但边界也要说清楚。官方 provider（如 Claude Official）不能走本地路由——唯一的例外是 Codex 的 OpenAI Official。路由开关的粒度是"每个工具"，加上每个工具一条故障转移队列；它不是一套"按任意维度编排代理规则"的平台，别按那种预期来设计工作流。

一次真实的请求流向

把前面的机制串起来，看一个常见任务：让 Claude Code 用上一家 OpenAI 格式的中转服务。

1. 在 Claude Code 页面点"+“添加 provider，选中转服务的预设或自定义配置，填入密钥。
2. 编辑该 provider，在高级选项里把"上游格式"设为 OpenAI Chat Completions（如果这家服务只提供 Chat Completions 端点）。
3. 打开本地路由总开关，再为 Claude Code 打开路由开关。
4. 此后 Claude Code 的配置文件指向 127.0.0.1:15721，你的请求路径变成：Claude Code 发出 Anthropic 格式请求 → 本地路由转换成 OpenAI 格式 → 转发给中转服务。
5. 中转服务挂了，路由自动切到故障转移队列里的下一个 provider；你可以在请求日志里核对每次的模型映射和错误详情。
6. 哪天想回到官方登录，把 provider 切回内置的 Claude Official（需先关闭该工具的路由），CC Switch 会把配置文件写回直连状态；退出应用前也会先写回。

这条链路解释了为什么它要把数据收进一个中心数据库：路由、故障转移、用量统计都依赖"真正知道每个请求该去哪"的这层本地控制点。

为什么它会选 Tauri 2、Rust 和 SQLite

它要同时处理本地文件系统、系统托盘、窗口生命周期、多种 CLI 配置格式、备份、同步和一部分网络代理逻辑，这已经超出"配置编辑器"的复杂度。官方声明的技术栈是 Tauri 2 · Rust · React 18 · TypeScript · SQLite：

• Tauri 2 负责桌面集成，体量和资源占用比 Electron 克制。
• Rust 承担底层文件、路由、同步和系统交互，适合"本地控制面板"这种对稳定性要求高的角色。
• SQLite 存放 provider、MCP、Skills、Projects、用量记录等核心数据，让所有对象有统一的数据源。

它在用户目录里维护的核心结构如下（Windows 在 C:\Users\<user>\.cc-switch）：

~/.cc-switch/
├── cc-switch.db        # SQLite 主数据库
├── settings.json       # 设备级设置，不参与云同步
├── backups/            # 默认每 24 小时自动备份，保留最近 10 份
├── skills/             # 可改为 ~/.agents/skills
├── skill-backups/      # 卸载或更新 Skill 前自动创建，保留最近 20 份
├── logs/               # 运行日志与崩溃日志
└── live-state.json     # 各工具当前直连还是走路由等设备状态

这套结构背后有几个值得注意的设计决定：状态收进中心数据库而不是散落文本；自动备份机制默认假设"用户会改错"或"同步可能失败”；Skills 的 symlink 与复制双模式，在节省空间和兼容性之间留了选择。项目还遵循一条"最小侵入"原则——即使卸载 CC Switch，各工具拿着剩下的配置文件照常能跑。

多设备同步的思路很务实

云同步没有另造一套账号体系，而是两条路：直接用 WebDAV（坚果云、Nextcloud、群晖 NAS 等）或 S3 兼容存储（AWS S3、Cloudflare R2、阿里云 OSS、腾讯云 COS 等）同步；或者干脆把 CC Switch 配置目录放进 Dropbox、OneDrive、iCloud 这类云盘文件夹。

这种设计的好处是直接、可理解，也便于和本地备份策略叠加。要注意范围：settings.json、设备状态和首次改写前的原始配置属于单机，不参与同步。它解决的是"多台机器配置一致"，不是团队权限系统——如果你期待审计、审批、角色管理，它不是那个方向。

安装并不复杂，真正要注意的是首次接管行为

系统要求：Windows 10 及以上；macOS 12（Monterey）及以上；Linux 需要 x86_64 或 ARM64、glibc 2.35+ 和 WebKitGTK 4.1（大致对应 Ubuntu 22.04+、Debian 12+ 和较新的 Fedora；RHEL/Rocky/Alma 8–9 暂不支持）。

macOS 推荐用 Homebrew（已签名公证，cask 在主仓库，无需额外 tap）：

brew install --cask cc-switch

Arch Linux：

paru -S cc-switch-bin

Windows 用户从 Release 页面下载 MSI 安装包或便携版（ARM 设备有 arm64 构建）；其他 Linux 发行版按包管理习惯选 deb、rpm 或 AppImage。Flatpak 不在官方发布物里，需要用 .deb 自行构建。

首次启动时，CC Switch 会自动把你已有的 Claude Code、Codex、Gemini CLI、Grok Build 配置各导入为一个名为 default 的 provider，并为这些工具和 Claude Desktop 各添加一个官方 provider——已配置的内容不会丢。真正需要理解的是"接管边界"：它只在切换时改写关键字段，其余配置不动，且首次改写前有备份。理解了这一点，就不必担心"工具被接管后失控"。

更稳妥的上手顺序：

1. 先确保目标 CLI 已在本机可用。
2. 启动 CC Switch，确认自动导入的 default provider 内容无误。
3. 先完成一条最小链路：添加并切换一个 provider，验证成功。
4. 再逐步接入 MCP、Skills、Prompts 或 Memory，一次一类，出问题时容易定位。
5. 用 Claude Code 的可以直接验证热切换；Codex、Gemini CLI、Grok Build 记得重开终端；Coexist 类工具去工具内部选择 provider。

哪些能力最值得用，哪些地方不要期待过高

它把"可重复维护的外围资产"抽象了出来，这是它最成熟的地方。但边界同样清楚：你仍然需要理解底层 CLI 怎么工作，尤其是配置生效时机和各工具特有的目录结构。

常见问题排查

• 请求 404 或 405：多半是上游格式选错，或者该开路由没开。对照 provider 实际提供的 API 类型检查"上游格式"。
• 连通性检查通过，请求仍然失败：这个检查只验证地址可达，不发真实模型请求，验不了密钥和模型名。开着路由时，去请求日志看具体错误。
• 切换后配置没变：确认用的工具属于哪一类——Switch 式工具要重开终端（Claude Code 除外），Coexist 式工具要在工具内部选 provider。
• Windows 下要管理 WSL 里的工具：在设置的配置目录覆盖里把对应工具指向 WSL 路径；WSL2 默认 NAT 网络下 127.0.0.1 连不通 Windows 侧的路由，需切换到 mirrored 网络模式。
• 服务器或无桌面环境：官方只有桌面版。社区维护的 cc-switch-cli 提供 TUI 和命令行模式，与桌面版共用 ~/.cc-switch 数据目录，可通过 brew install cc-switch-cli 安装。

谁最适合用，谁其实可以先不装

如果满足下面任一情况，CC Switch 往往值得装：

• 同时使用两种以上 AI 编程 CLI。
• 需要在官方 API、中转服务和自建兼容接口之间频繁切换，或者想在 Claude Code 里用上 GPT 系、Gemini 系模型。
• 希望把 MCP、Skills 和常用上下文资产集中管理。
• 有多设备同步需求，不想在每台机器上重复配置一遍。

反过来说，如果你只用单一 CLI、始终走同一个官方 provider，也不排斥手改配置文件，它暂时给不了决定性收益。它的优势集中在"多工具、多 provider、多上下文资产并存"的场景，而不是所有人装上都会立刻提效。

自测题

完成阅读后，试着回答以下问题：

1. CC Switch 解决的核心问题是什么？它不解决什么问题？
2. Switch 与 Coexist 两种接入模式的区别是什么？各覆盖哪些工具？
3. 为什么 Claude Code 支持热切换，而 Codex 需要重开终端？
4. Hermes Agent 的 Memory 面板和传统 Prompts 面板有什么区别？
5. Local Routing 能做什么、不能做什么？为什么官方 provider 不能走本地路由？
6. 开启本地路由后，配置文件里为什么会指向 127.0.0.1？这对排查问题有什么帮助？
7. CC Switch 的云同步同步的是什么？不同步的是什么？
8. 如果你要在一个团队里推广 CC Switch，你会怎么解释它的边界？

进阶路径

已经装好了，想进一步用好：

• 最小化验证链路：装好后先只配置一个 provider，验证切换成功，再逐类接入 MCP、Skills、Prompts，避免一次配太多导致出错时无法定位。
• 理解 Switch 与 Coexist：主要用 Claude Code 的，体验热切换；也用 Codex 或 Gemini CLI 的，养成"改完配置重开终端"的习惯；OpenCode 这类共存式工具则要去工具内部选模型。
• MCP 同步策略：先在一个工具里配好 MCP，再用统一面板勾选同步到其他工具，而不是每个工具单独配一遍。
• 用 Projects 隔离多套配置：不同项目用不同 provider 组合的，把每组状态存成 Project，从托盘一键切换。
• 多设备同步验证：在一台机器上改配置，确认同步到另一台机器后，各 CLI 能正常读取。

想参与项目或深度定制：

• 仓库地址：https://github.com/farion1231/cc-switch
• 如果你发现某个 CLI 的配置格式变了导致 CC Switch 无法正确解析，可以先查阅 CONTRIBUTING.md，开 issue 讨论再提 PR。
• 技术栈是 Tauri 2 · Rust · React 18 · TypeScript · SQLite，熟悉 Rust 的可以参与底层文件处理和路由逻辑的开发。

总结

CC Switch 最强的地方，不是替模型做决定，而是减少配置漂移和上下文碎片。它把原本分散在多个 CLI、多个目录、多个格式里的东西集中起来，让"切 provider"“同步 MCP"“复用 Skills"“找回会话"“维护工作区上下文"这些动作有了统一入口；本地路由再把协议差异和故障转移也接了过去。

如果你正在从单一 AI 编程工具走向多工具协作，它值得认真评估；如果你只想找一个"自动把一切都抹平"的万能壳，它不是那种产品——它呈现各工具的差异，而不是掩盖差异。把这条边界看清楚，反而更容易用好它。

相关资料

• CC Switch GitHub 仓库
• CC Switch Releases
• 英文用户手册
• 项目更新日志
• 官方主页 ccswitch.io