它自称只是个换供应商的小工具。可一个换供应商的动作，凭什么长成 13 万 star、九个 CLI 共用的控制台？
先说结论。CC Switch 是一个开源桌面应用，用来切换 AI 编程工具的模型供应商。它管着 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、MiniMax Code 这一串命令行工具背后的配置，让你不用再手改 JSON、TOML 和 .env。
按官方仓库的公开数据，这个项目 2025 年 8 月 4 日建仓，到 2026 年 9 月已经拿到 133,232 个 star、9,186 个 fork，发过 54 个版本，最新是 v3.20.3（2026 年 9 月 11 日）。它甚至进了 GitHub 全球 star 排行榜的前一百名。
这里有个说不通的地方。切换供应商这件事，难度约等于改两个字符串。一个改环境变量的活儿，为什么会有人做成一个常驻桌面的应用，还越做越重？
这就是这篇文章要拆的问题。它不是测评，也不是推荐。我们把它的定位、它动过的文件、它后来长出来的路由层、以及那些没人愿意提的坑，一层层摊开看。
先看它要解决的那个麻烦，到底长什么样。
你把场景还原一下就明白了。周一下午，Claude Code 的额度见底，你打算切到公司买的中转站。于是打开 ~/.claude/settings.json，在 env 段里改两个字段：ANTHROPIC_BASE_URL 换成中转站的地址，ANTHROPIC_AUTH_TOKEN 换成新 Key。保存，关掉终端，重新开一个。
半分钟的事，对吧。问题是下一个半小时不一定。
因为你还装着 Codex。它不看 JSON，看的是 ~/.codex/config.toml 里的 model_provider 和 [model_providers.custom]，Key 又单独放在 ~/.codex/auth.json 里。Gemini CLI 又是第三种格式。三个工具，三套语法，三份凭据。改错一个字符，你拿到的是 401，不是友好的报错。
官方文档把这个痛点归纳成四句话，每句都挺扎心：
第四句最要命。前三条是麻烦，第四条是损失。主供应商抽风的时候，你不是少了个工具，是整条工作流停在那。
麻烦是真的，但它值一个桌面应用吗？先把 CC Switch 这个项目本身摊开看。
用一个界面管九个 CLI，这是它的核心卖点。
它的形态很具体：Tauri 2 写的跨平台桌面应用，后端 Rust，前端 React 加 TypeScript，支持 Windows、macOS、Linux，MIT 协议开源。仓库地址是 github.com/farion1231/cc-switch，作者是 @farion1231，官方声明唯一官网为 ccswitch.io。
它自称的能力清单可以拆成五块：
| 能力 | 具体是什么 |
|---|---|
| 供应商切换 | 50+ 内置预设，含 AWS Bedrock、NVIDIA NIM 和大量社区中转；也可以自己填自定义配置 |
| 多应用统一 | 一个界面管理 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、MiniMax Code |
| 扩展管理 | MCP 服务器、Skills、Prompts 统一面板，配双向同步 |
| 本地路由 | 本机起一个路由服务，做协议转换、热切换、故障转移、请求日志与用量统计 |
| 本地存储 | 配置与 Key 存在本地 SQLite 库，支持 Schema 迁移、自动备份 |
注意一件事：受管应用的数量，官方自己的口径都不统一。仓库标题列了九个（含 Grok Build 与 MiniMax Code），官网首页和用户手册写的是七个，仓库 description 里点名的只有六个。引用的时候最好别写死数字，写「七到九个」。
时间线上有两个绕不开的节点。第一个是 2025 年 8 月 4 日建仓，那会儿它只是个 Claude Code 的供应商切换器，名字里的「cc」就是 Claude Code。第二个是 v3.9.0，版本说明的标题直接写着 Local API Proxy, Auto Failover, Universal Provider。这一版之后，它从「帮你改配置的工具」变成了「帮你接管流量的中间层」。项目性质在这一版变了。
再往后就顺理成章：v3.13.0 加了系统托盘快速切换和轻量模式（只留托盘，销毁主窗口），v3.16.4 官方庆祝进入 GitHub 全球 star 榜前一百。第三方统计给出的当前排名是全球第 77 位，在 Rust、Tauri、OpenCode 这几个 topic 下都是第一。
好。一个改配置的工具，凭什么值这么多 star？答案藏在它到底动了你电脑上的哪些文件里。
把它的写入动作逐个摊开，才看得出设计上的取舍。
先把落点列清楚。每个 CLI 的配置格式都不一样：
| 应用 | 配置文件 | 关键字段 |
|---|---|---|
| Claude Code | ~/.claude/settings.json | env 段下的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN |
| Codex | ~/.codex/auth.json ~/.codex/config.toml | OPENAI_API_KEY；model_provider、model、[model_providers.custom] 的 base_url 与 wire_api |
| Gemini CLI | ~/.gemini 下的配置 | GEMINI_API_KEY、GOOGLE_GEMINI_BASE_URL、GEMINI_MODEL |
| OpenCode | opencode.json | provider、model、small_model、mcp |
| Claude Desktop | 应用内 3P 供应商配置 | 直连或模型映射模式 |
真正的设计取舍在下一层。它没有把 SQLite 当成缓存，而是当成了唯一真相源。供应商、MCP、Prompts 全部存在本地库里，设备设置另存 JSON，那些 live 配置文件只是「投影」。切换供应商这个动作，本质是在库里换一个当前项，然后把值重新投影回各家的配置文件。
这么设计解决的是同一件事的两种翻车方式。第一种是文件写坏：所有写入都走原子写入，先写临时文件再 rename。半截文件不会被留在原地。第二种是改错了回不去：备份目录在 ~/.cc-switch/backups/，自动备份默认 24 小时一轮、保留最近 10 份，还可以把整个库导出成一个带时间戳的 SQL 文件。
有一个细节挺能说明它的态度。写配置之前，它会先检查目标目录存不存在。你没装 Claude Desktop，它就不会替你造一份指向空气的「幽灵配置」。这种判断听起来是小事，但一个能同时改九个工具配置的程序，如果每个都敢无脑写，你的电脑两周后就会变成配置垃圾场。
到这一步，它已经站在了你所有请求的入口位置。入口拿到了，下一步的诱惑就很好猜了。
这是整个项目最关键的一次转身，也是最容易被误解的地方。
先讲它不得不做的原因：协议不通。
Claude Code 只会说 Anthropic 的 Messages 协议，请求打到 /v1/messages。而你想接的很多上游，说的是 OpenAI 的 Chat Completions 或者 Responses 协议。两边的请求体结构、SSE 流式事件格式、工具调用的描述方式、图片和 PDF 的编码、思考配置，全都不一样。直连的结果不是效果差，是直接 400 报错。
所以它在本机起了一个服务，默认监听 127.0.0.1:15721，然后把 Claude Code 的配置指过来：
注意那个占位符。真实密钥不进 live 配置文件，只留一个 PROXY_MANAGED 标记，真正的 Key 存在本地库里，由路由转发时注入。这一手同时解决了两个问题：配置文件可以随便截图，密钥也不在明文里躺着。
代价是刚性的：你的请求要过一次本机。换来的是四件事。
这块它做得比「挂了就切」细。官方手册里给的是默认参数：
| 参数 | 默认值 | 含义 |
|---|---|---|
| 失败阈值 | 通用 4 次 / Claude 8 次 | 连续失败到这个数，熔断器打开 |
| 恢复成功阈值 | 2 次 / 3 次 | 半开状态下连续成功，恢复正常 |
| 恢复等待 | 60 秒 / 90 秒 | 熔断后等这么久再试 |
| 错误率阈值 | 60% / 70% | 按错误率触发，不只是看连续次数 |
| 流式首字节超时 | 60 秒 / 90 秒 | 等不到第一个字就算失败 |
| 最大重试 | 3 次 / 6 次 | 失败后的重试上限 |
熔断器是三态机：关闭、打开、半开。界面上给了健康徽章，连续失败 0 次是绿的，1 到 2 次转黄，3 次以上变红。故障转移走队列，P1 不行就 P2。而且熔断状态是按「应用:供应商」记账的，Claude Code 那边的熔断不会连累 Codex。这些只是默认值。通用一套、Claude 一套，Gemini 的重试上限又是单独一个数。真出问题的时候，值得去设置里逐项看一眼，别默认它一定兜得住。
同为「本地跑一个代理」，它和专门做路由的工具有个分工上的差别。那类工具解决的是「这次请求该用哪个模型」，属于策略层；CC Switch 解决的是「我这台机器上有哪些供应商、怎么统一配置、出事怎么兜底」，属于控制层。两者能叠着用。
入口流量接管了，配置中枢也建立起来了。但还有一块地它顺手也圈了进去。
这部分比供应商切换更琐碎，但日常痛感更强。
MCP 服务器的落点和供应商配置一样分散，格式还各不相同：
| 应用 | MCP 配置落点 | 格式 |
|---|---|---|
| Claude | ~/.claude.json 的 mcpServers | JSON |
| Codex | ~/.codex/config.toml 的 [mcp_servers] | TOML |
| Gemini | ~/.gemini/settings.json 的 mcpServers | JSON |
| OpenCode | opencode.json 的 mcp | JSON |
它把这四个落点收进一个面板，后面站一个统一的服务在协调。每次你新增服务器或者拨动某个应用的开关，它对比新旧状态，只动该动的那几个文件，关闭开关就从对应文件里移除。所谓「双向」是两层意思：面板上的配置能下发到各 CLI，各 CLI 里已经存在的 MCP 配置也能导入回来。
麻烦的地方在格式差异，得一个个抹平。Gemini 那边 http 类型的字段名要改写成 httpUrl，超时单位要换成毫秒；OpenCode 那边 stdio 要变成 local，command 加 args 要合并成一个 command 数组，sse 和 http 统一成 remote。写之前照样先做目录存在性检查，写入照样是原子写入。
Skills 走的是另一套。真相源放在 ~/.cc-switch/skills/，v3.13.0 之后可以切到社区约定的 ~/.agents/skills，再分发到各个 CLI 自己的 skills 目录。分发方式有两种可选，软链接或者复制。软链接省空间、改一处全局生效，缺点是有些工具不认符号链接；复制能兼容，但一次更新要写多份。更新检测靠 SHA-256 内容哈希，不看时间戳。卸载前会自动备份到 ~/.cc-switch/skill-backups/，最多留 20 份。
读到这，这个工具已经相当完整了。完整的工具用起来，绊脚的地方也就具体了。
坑都是真的，多数能在官方 FAQ 和社区帖里找到。
这是官方 FAQ 里的头号问题。原因是 Claude Code 和 Codex 在进程启动时读配置，你改了文件，它不知道。必须关掉当前终端会话，重新开一个。Gemini 相对友好，托盘切换可以即时生效。
官方教程里专门点过这个。ANTHROPIC_AUTH_TOKEN 和 ANTHROPIC_API_KEY 看起来是同一件事，实际走的是不同的请求头。填错的话，请求会以 x-api-key 发出去，很多 OpenAI 兼容网关直接回 401 或 403。你不是配置错了地址，你是配置错了身份。
官方支持 WebDAV 云同步，也提过 Dropbox、OneDrive、iCloud 这些路径。但社区里有实测反馈：把配置目录直接放进 iCloud 或 OneDrive，多设备之间会互相回写、互相覆盖。多设备同步要么用官方的 WebDAV 方案，要么干脆别同步。
开启路由前它备份原配置，关闭时恢复。但如果路由进程异常退出，live 配置有概率停在「指向本地端口」的状态。这时候 Claude Code 会连不上，你得重新保存一次或者重启应用。挺小的一件事，但在你正急着干活的时候出现，体感很差。
15721 被别的程序占了，代理直接起不来，官方 FAQ 把端口占用列为代理启动失败的首要原因。另外有使用心得提到，SQLite 处理含中文的路径时偶尔出现编码异常。机器上路径结构比较复杂的，值得留个心。
V2EX 上有个帖子问「claude-cli 通过 ccswitch 配置国产模型，真的 ok 吗」，回复基本分成两派。
第三句其实最有信息量。对只用一家、只用一个 CLI 的人来说，这个工具确实是多余的。它是给「手上不止一套凭据」的人准备的。这句话我们留到最后一章继续用。
但坑还不是最需要小心的部分。真正该想清楚的是它带来的代价。
有四件事，用之前最好知道。
所有供应商凭据都落在本地 SQLite 库里。好处很实在：不上传云端，没有服务器能拿到你的 Key，这也是第三方安全评估给它高分的原因。代价同样实在：这台机器成了单点。官方自己在文档里提醒，不要手动复制或分享 ~/.codex/auth.json，里面是官方登录缓存和 Access Token。装了这个工具之后，这句话的分量比装之前更重了。
这点和工具无关，是「用中转站」这件事本身的属性。你的提示词、代码片段、商业资料，都要经过那家服务商的服务器。CC Switch 官方文档也要求用户自行阅读目标网关关于计费、合规和数据留存的条款，社区的使用心得里也有明确提示：不确定对方数据留存策略时，别在生产环境对话里泄露敏感内容。
这一条得直说。打开官方仓库，正文之前是一大片赞助商区块，三十来家 API 中转与聚合服务商，几乎每家的链接都带 aff=cc-switch 返利参数或专属优惠码。官网首页也直接写着「如果您需要稳定、高性价比的 API 中转服务，欢迎了解一下 CC Switch 的赞助商」。
项目免费、开源、MIT 协议，收入靠赞助和返利，这件事它是公开挂出来的，没有藏。但结论要你自己下：预设列表里的 50 多个供应商，哪些是真好用，哪些只是挂了广告，工具不会替你判断。预设只是个便利，不是背书。
它有个功能是把 ChatGPT 订阅的 Codex 额度「反代」出来给别的工具用。官方文档对此写得很清楚：这条路径涉及逆向的 OAuth 流程，可能违反 OpenAI 服务条款，账号可能被标记为可疑自动化并施加临时或永久限制，长期可用性不作保证，启用即自担风险。另外这部分流量和你官方客户端的用量计在同一份额度里，重度使用会更快触顶。
还有一件和代码无关、但每个用户都该知道的事：仿冒站点。官方在每次版本公告里固定挂一段防伪声明，说发现多个山寨网站冒用 CC Switch 名义诱导付费、收集账号信息，部分已造成实际经济损失，并强调唯一官网是 ccswitch.io，源码只在 GitHub 上，任何向你收费、要求充值或索取登录凭据的「CC Switch」都是假冒的。搜索这个工具时，请直接从 GitHub Releases 下载。
代价摊完了。最后一个问题只剩：你该不该装。
按你的实际情况分，答案很干脆。
不必装的情况：你只用一家官方订阅，只用 Claude Code 一个工具。改配置就是改两个字符串，装一个常驻应用不划算。前面那位 V2EX 用户说的是对的。
值得装的情况：你手上同时有官方订阅、国内 Coding Plan 和自有 API Key，需要频繁切换；或者同时用三个以上 CLI，MCP 配置已经开始打架；或者你需要额度可见，以及主供应商抽风时不想手动救火。这三条里中两条，它省下的时间就够本了。
最后一句实在话。CC Switch 本身是个配置管理工具，真正决定你体验的不是它，是你接进去的那家供应商。它能让切换变快、让故障转移变自动、让用量变可见，但它挡不住一家网关跑路，也修不好一个掺了水的模型。工具解决工具的问题，选择解决选择的问题。
所以想问一句：你上一次因为额度用完被迫中断任务，是什么时候？