CC Switch 是什么：一个桌面应用管住多个 AI 客户端的配置

2026-08-10

同时用 Claude Code 和 Codex 的人，多半都干过同一件事：为了换一个上游，去 ~/.claude 和 ~/.codex 里手工改配置，改完还要记住上一份是什么样子。CC Switch 要接管的就是这件事。

但它接管的方式和很多人第一反应想的不一样。它不是一个常驻在你和模型之间的转发服务，也不是把你的 CLI 包一层壳。它是一个桌面应用，替你改写你本机那些 CLI 自己的配置文件，然后把所有配置版本存进它自己的一份数据库。这个区别决定了它的能力边界，也决定了几个看上去像 bug 的行为其实是设计推论。

以下全部基于我们本地 clone 的 cc-switch 仓库快照 c39c903（提交日期 2026-08-10），仓库内版本号 3.19.2。我们只读源码与文档文本，没有安装也没有运行过这个桌面应用，所以不涉及任何界面外观与操作手感的描述。

2026-08-31 补记：这篇写完之后上游发了 v3.20.0 与 v3.20.1。受管应用已经从八个变成九个（新增 Pi），而 README_ZH.md 到 v3.20.1 仍写着「八个工具」、用户手册的那张表仍只列七个——本文下面讲的「别把某一处的清单当成能力全集」，在新版本里不但没过时，差距还拉大了。下文所有数字仍以 v3.19.2 为准。

先把它的身份钉死

版本号在三个地方是一致的：package.json:3、src-tauri/Cargo.toml:3、src-tauri/tauri.conf.json:4 都是 3.19.2。Tauri 配置里 productName 是 “CC Switch”，identifier 是 com.ccswitch.desktop（src-tauri/tauri.conf.json:3-5）。license 字段是 MIT（package.json:20、src-tauri/Cargo.toml:6），LICENSE 首行写 “MIT License”，版权行是 “Copyright (c) 2025 Jason Young”（LICENSE:1-3）——许可条款请以官方 LICENSE 原文为准，本文不解读商用边界。README 里另有一句要留意：标注「唯一官方网站：ccswitch.io」（README_ZH.md:15）。

截至 2026-08-10 我们采集时，farion1231/cc-switch 在 GitHub 上是 126030 star、8577 fork、2129 个 open issue，建仓于 2025-08-04。这三个数是并列的事实，我们不由 star 数推导任何关于质量或成熟度的结论，也不由 issue 数推导反面结论。

还有一个小口径差值得先摆出来：package.json:4 与 src-tauri/Cargo.toml:4 里的 description 逐字相同，都是 “All-in-One Assistant for Claude Code, Codex & Gemini CLI”，只点了三个工具；而 README 多处自称八个工具（README_ZH.md:5、:205、:225、:260）。工具清单这件事在仓库里不止两处口径，我们另有一篇专门讲，这里只是提醒你：别把某一处的清单当成能力全集。

反直觉的那一处：它管的是「文件」，不是「流量」

README 的 FAQ 里有一句写得很明白：「本软件的设计原则是’最小侵入性’，即使卸载本软件，也不会影响应用的正常使用。」（README_ZH.md:288）英文版同义（README.md:287）。

这句话不是客套。它是理解整个产品的钥匙。既然卸载之后你的 CLI 还要能正常跑，那就意味着 CC Switch 平时并没有站在请求链路上——它写完文件就退场，CLI 读的还是 CLI 自己那份配置。

架构表述那一节把这套机制拆得更细（README_ZH.md:424-429）：

SSOT（单一事实源）：所有数据存储在 ~/.cc-switch/cc-switch.db（SQLite）
双层存储：SQLite 存可同步数据，JSON 存设备级设置
双向同步：切换时写入 live 文件，编辑当前供应商时从 live 回填
原子写入：临时文件 + 重命名模式防止配置损坏
并发安全：Mutex 保护的数据库连接避免竞态条件
分层架构：Commands → Services → DAO → Database

这里的「live 文件」就是各 CLI 自己的那份配置。双向同步这条尤其要看清方向：切换供应商是数据库写向 live 文件；而你去编辑「当前供应商」时，是从 live 文件回填进数据库。也就是说，你在 CC Switch 之外手改过的东西会不会、什么时候被带回库里，只有这两条路径给了答案：走切换就是库覆盖文件，走编辑当前供应商就是文件回填进库。这两条之外还有没有别的同步时机，文档没有说明，我们也没有核实，这里不替它推断。

顺着「最小侵入性」往下推，就能解释那个最常被当成 bug 的行为：为什么总有一个正在激活中的供应商删不掉。README 的解释是，系统总会保留一个正在激活中的配置，因为如果把配置全部删光，对应那个应用就没法正常工作了；不常用的应用，文档给的做法是在设置里关掉它的显示（README_ZH.md:290）。这不是删除功能坏了，是「卸载我也不能影响你的 CLI」这条原则的必然结果。

它替你做的六件事，落在六个 Service 上

紧接着架构那一节，README 列出的核心组件正好六个（README_ZH.md:433-438），依次是 ProviderService、McpService、ProxyService、SessionManager、ConfigService、SpeedtestService。把这六个名字当成功能地图看，比看卖点行有用得多。

按前面那条主线分组，真正和「改写 live 文件」直接挂钩的是头两个。ProviderService 对应的就是本文一路在讲的那条主路径——供应商切换与回填；McpService 那一块 README 另有交代，MCP 统一面板声称覆盖 6 个工具（README_ZH.md:236）。ConfigService 则可以和后面要讲的 ~/.cc-switch/backups/（README_ZH.md:306）对着看，它是写入动作的安全网那一侧。

剩下三个里，ProxyService 值得单拎出来提醒一句：README 另一处写了应用级代理接管可以为 4 个工具独立配置（README_ZH.md:232），说明代理是一条要你自己开的功能，而不是默认形态。前面说的「不站在链路上」讲的是默认的配置切换路径，代理模式是另一套东西，它的管线、熔断与故障转移我们另有专篇，本文不展开。至于 SessionManager 与 SpeedtestService，名字大致能猜到指向哪一类能力，但我们没有到源码里核实过它们的实际范围，这里就不替它们下定义了——你要用到再自己去翻 src-tauri/src/services/。

README 自称的覆盖面也是分层的，别混成一个数：MCP 统一面板声称覆盖 6 个工具（README_ZH.md:236）、「通用供应商」声称一份配置同步到 3 个（Claude Code、Codex、Gemini CLI，README_ZH.md:226）、应用级代理接管声称可独立配置 4 个（README_ZH.md:232）。也就是说，「支持某工具」和「某个具体功能覆盖某工具」是两件事，同一个工具在不同功能上的覆盖程度并不齐平。

另外两条 README 口径：Deep Link 的 scheme 是 ccswitch://（README_ZH.md:252），Tauri 配置里的 desktop schemes 数组也确实是 ["ccswitch"]（src-tauri/tauri.conf.json:57-60）；界面语言声称 4 种（简中 / 繁中 / 英 / 日，README_ZH.md:253）。

切完要不要重启：这里有一处文档口径差

这是新手最容易踩的一步。README 快速开始那一节的说法是：切换之后要重启终端或对应的 CLI 工具，Claude Code 除外（README_ZH.md:337）；FAQ 第 2 条写得更直白——大多数工具需要重启终端或 CLI，例外的是 Claude Code，「它目前支持供应商数据的热切换，无需重启」（README_ZH.md:265-267）。

而用户手册 1.4 的那张生效方式表，把 Gemini 也列进了「即时生效（每次请求重新读取配置）」，并且这张表只覆盖 5 个应用，没有 Claude Desktop、Grok Build 和 Hermes（docs/user-manual/zh/1-getting-started/1.4-quickstart.md:35-39）。

两处口径不一致。按我们的纪律：说完差异就停，不推断哪一处「才算数」，也不推断原因。对你的实际影响只有一句——如果切换之后行为没变，先把终端和 CLI 重开一遍再排查别的，不要因为在某处文档里看到「即时生效」就把重启这一步跳过去。

它把什么放在了你本机

这一段请认真读，因为涉及的是敏感数据。README FAQ「我的数据存储在哪里」列了 5 项（README_ZH.md:304-308）：数据库 ~/.cc-switch/cc-switch.db（SQLite，存供应商、MCP、提示词、技能）、本地设置 ~/.cc-switch/settings.json（设备级 UI 偏好）、备份 ~/.cc-switch/backups/、技能目录 ~/.cc-switch/skills/、技能备份 ~/.cc-switch/skill-backups/。

代码侧对得上：默认配置目录是 get_home_dir().join(".cc-switch")（src-tauri/src/config.rs:208），数据库文件路径拼在 get_app_config_dir().join("cc-switch.db")，注释里明写「数据库文件位于 ~/.cc-switch/cc-switch.db」（src-tauri/src/database/mod.rs:99-101）。settings.json 那一份的注释写的是「存储设备级别设置……不随数据库同步」（src-tauri/src/settings.rs:339）——这就是上面「双层存储」的落地形态：该同步的进库，不该跨机器带走的留在 JSON 里。

数据库还有一个版本号常量：SCHEMA_VERSION: i32 = 16（src-tauri/src/database/mod.rs:56），CHANGELOG 里 3.19.2 的升级说明也写 “SCHEMA_VERSION stays at 16”（CHANGELOG.md:56）。

关键提醒：供应商配置里包含 API Key，这些是你本机的敏感数据。它们进了 ~/.cc-switch/cc-switch.db，同时也会被写进 ~/.claude、~/.codex 这些 CLI 的真实配置文件。备份目录里同样会留下历史副本。我们没有核实过它的存储加密方式，因此不会写「安全」或「不会泄漏」之类的话——你要做的是把这几个路径当成和私钥同级的东西对待：别丢进公共仓库，别随手打包发给别人。备份与保留份数的具体规则（README 写死的份数与代码里可配的设置项之间还有一处差异）我们另有一篇专门讲。

你可以自己核的几件事

不用装，clone 下来读文本就能核。三条最值得先跑的：

git clone https://github.com/farion1231/cc-switch
cd cc-switch
git log -1                      # 看你手上是哪个快照
sed -n '3p' package.json        # 版本号
sed -n '286,292p' README_ZH.md  # 「最小侵入性」那一段
sed -n '424,438p' README_ZH.md  # 架构表述与六个核心组件

以上为按仓库中的文件与行号组合的示例命令，我们没有在本机运行验证过，行号也会随版本漂移，请以你自己 clone 到的内容为准。

想验证「它管的是文件不是流量」这个判断，最直接的对照是：把 README 那句最小侵入性（README_ZH.md:288）和架构小节里的「双向同步：切换时写入 live 文件」（README_ZH.md:426）放在一起读，再去 src-tauri/src/config.rs:208 确认配置目录的默认拼法。三处指向同一件事。

边界与还没定型的部分

有几处仓库自己标了风险，照实抄给你：

用户手册 1.5 有一节 「OAuth 认证中心（Beta）」，写明是 v3.13.0 新增，统一管理三类第三方 OAuth 凭据（docs/user-manual/zh/1-getting-started/1.5-settings.md:277-287）。同节的警告原文说这些账号型反向代理「使用逆向接入的 OAuth 流程，存在账号与服务条款风险」，「复用上游产品的 OAuth 客户端可能不受官方支持，并可能导致服务商限制或封禁账号」，要求使用者自行承担风险（同文件 :310）。这段我们只转述，不做任何绕开平台条款的建议。
CHANGELOG 记了一条 3.19.2 的已知限制：统一 OMO 配置文件如果含块注释 /* … */，写入会被拒绝并报错，需要先删掉块注释才能切换供应商，直到上游 JSON5 writer 修好为止（CHANGELOG.md:61）。
同版本还记了两条：Codex 交叉计数的修复只对之后的记账生效，历史行 “deliberately not rewritten”，不会自动重建（CHANGELOG.md:57）；3.19.2 没做 schema 迁移，因此不触发升级前备份（CHANGELOG.md:56）。

什么情况下你不需要它

也说反面。如果你只用一个 CLI、只连一个上游、从不换 Key，那这套东西给你的增量非常有限——你要维护的本来就只有一份配置文件。它的价值来自「配置版本数 × 工具数」这个乘积：工具越多、上游越多、来回切得越频繁，手工改文件的出错成本才越高。

反过来，如果你已经在多个工具之间来回切，那真正要评估的问题也不是「好不好用」，而是这三条：你能不能接受把 API Key 集中放进本机一份 SQLite；你的工作流能不能配合「切完要重启终端」这个前提；以及你是否需要 MCP、Skills 这些切换之外的功能——那部分的覆盖工具数和供应商切换并不相同。

本专题全部 40 篇

下面这份目录与专题页一致，按主题分组；每篇都是独立的，可以只挑你现在要用的那几篇看。

认识与安装

供应商与预设：这个项目的主线

后端架构与 SQLite 存储

本地代理、熔断与故障转移

MCP / Prompts / Skills / 会话 / Deep Link

用量、定价与云同步

本文依据 CC Switch 官方仓库（github.com/farion1231/cc-switch）的 README、docs/ 下的用户手册与发布说明、 src/config/ 的预设定义与 src-tauri/src/ 的后端源码整理，核对日 2026-08-10，对应仓库快照 c39c903。本文内容为仓库源码与文档口径，我们没有安装或运行过这个桌面应用，因此不涉及界面外观、操作手感与切换速度的任何描述。文中出现的阈值与默认值均为源码中的默认配置，不构成对实际运行结果的保证。该项目仍在快速迭代，版本与默认值随时可能变动，请以仓库最新内容为准。许可条款请以官方 LICENSE 原文为准，本文不构成法律意见。安全相关做法请结合自身环境评估，本文不构成安全方案建议。

留言讨论

评论发布后会被人工复核，违规内容将被删除。

如果发表没有反应，可以前往联系我们告诉我们。