引言
"一键切换 API Provider，MCP、Skills、Prompts 集中管理——不用再手动编辑 JSON/TOML/YAML 配置文件。"
这是"一天一个开源项目"系列的第 234 篇。今天的项目是 CC Switch。
现在同时用好几款 AI 编程工具已经是常态——Claude Code 跑一个项目,Codex 跑另一个,偶尔还要切到 Gemini CLI 或 Grok Build 对比效果。问题是这些工具各自有一套配置格式:Claude Code 用一种 JSON 结构,Codex 用 TOML,Gemini CLI 又是另一套 YAML——每次换 Provider、换 API Key、换模型,都要翻到对应工具的配置文件里手动改,MCP 服务器和 Skills 还得在每个工具里各配一份。
CC Switch 把这件事做成了一个统一的桌面应用:一款工具,管理十款 AI 编程工具(Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code)的 Provider 配置,支持一键切换、90+ Provider 预设,还能做本地请求的格式转换路由(Routing)和多 Provider 模型聚合(Aggregation)。
142.8k Stars,MIT 协议,基于 Tauri 2 + Rust + React 18 构建,目前是这个赛道里规模最大的开源项目之一。
你将学到什么
- CC Switch 如何用 Switch/Coexist 两种模式统一十款工具的配置管理方式
- Direct、Routing、Aggregation 三种连接模式的具体区别和适用场景
- "最小侵入"设计理念:切换 Provider 为什么不会破坏你手动加的插件和 Hook
- 本地请求路由的格式转换与故障转移(Failover)机制
- 数据存储设计:
~/.cc-switch目录结构与云同步方案
前置知识
- 使用过至少一款 AI 编程 CLI 工具(Claude Code、Codex、Gemini CLI 等)
- 了解 API Provider、Base URL、API Key 这些基本概念
- 可选:了解 MCP(Model Context Protocol)的基本用途会更容易理解集中管理部分
项目背景
项目简介
CC Switch 的官方定位是:"面向 Claude Code、Codex、OpenCode、OpenClaw、Grok Build 和 Hermes Agent 的跨平台桌面全能助手"。更完整的说法是"Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes Agent、Pi 和 MiniMax Code 的全能管理器"。核心价值主张:"一键切换 API Provider,MCP、Skills、Prompts 集中管理——不用再手动编辑 JSON/TOML/YAML 配置文件"。
团队与项目信息
- 作者:Jason Young(farion1231)
- 协议:MIT License
- 技术栈:Tauri 2、Rust、React 18、TypeScript、SQLite
- 官网:ccswitch.io
项目数据
- ⭐ GitHub Stars:142,800+
- 🍴 Forks:9,500+
- 👀 Watchers:264
- 📄 协议:MIT
主要功能
解决什么问题
没有 CC Switch 时的多工具管理：
Claude Code → 配置文件是 JSON，Provider 信息藏在深层嵌套字段
Codex → 配置文件是 TOML，格式完全不同
Gemini CLI → 配置文件是 YAML，又是另一套结构
↑ 每换一次 Provider/API Key/模型，都要分别打开对应工具的配置文件手改
↑ MCP 服务器、Skills、Prompts 要在每个工具里各自配置一份，无法共享
CC Switch 的做法：
一个桌面应用，统一管理十款工具的 Provider 配置
↓ 一键切换，90+ 预设 Provider（AWS Bedrock、NVIDIA NIM、社区中转等）
↓ MCP、Skills、Prompts 集中管理一次配置，多工具复用
↑ 切换只改动必要的连接字段（endpoint/key/model）
↑ 插件、Hook、自定义配置保持不变
使用场景
-
同时使用多款 AI 编程 CLI 的开发者
- 想要统一管理 Provider 和 API Key,而不是在每个工具的配置文件之间来回切换
-
需要在多个 Provider 之间频繁切换测试的用户
- 对比不同模型/Provider 的效果,一键切换而不用手动改配置文件
-
想要跨工具复用 MCP 服务器配置的团队
- 不想在 Claude Code、Codex、Gemini CLI 里分别配置同一套 MCP 服务器
-
想在 Claude Code 里用 GPT,或者混用不同厂商模型的用户
- 通过 Routing 模式做本地格式转换,实现跨 Provider 格式兼容
-
需要追踪多 Provider 使用量和费用的用户
- 在 Provider 卡片和系统托盘上直接查看 Token 用量、花费、订阅额度,不需要分别打开每个厂商的后台
快速开始
安装:
# macOS
brew install --cask cc-switch
# macOS 升级
brew upgrade --cask cc-switch
# Arch Linux
paru -S cc-switch-bin
基本使用流程:
1. 在侧边栏通过预设或自定义配置添加一个 Provider
2. 通过主界面、系统托盘或项目切换器切换 Provider
3. 切换生效方式因工具而异：Claude Code 即时生效，其他工具可能需要重启
4. 可选：开启 Routing/Aggregation 标签页，实现跨格式转换或多 Provider 聚合
5. 通过"Apps"页面管理已安装 CLI 工具的版本
核心特性
1. 两种配置管理模式
| 模式 | 含义 |
|---|---|
| Switch | 同一时刻只有一个 Provider 处于激活状态 |
| Coexist | 多个 Provider 同时写入该工具自己的配置文件 |
2. 工具支持能力矩阵
| 工具 | 配置模式 | 本地路由 | 聚合 | 托盘切换 | MCP | Skills | Prompts | 会话 | 用量统计 |
|---|---|---|---|---|---|---|---|---|---|
| Claude Code | Switch | ✓ | ✓ | ✓ | ✓ | ✓ | CLAUDE.md | ✓ | ✓ |
| Claude Desktop | Switch | 仅模型映射 | – | ✓ | – | – | – | – | 仅模型映射 |
| Codex | Switch | ✓ | ✓ | ✓ | ✓ | ✓ | AGENTS.md | ✓ | ✓ |
| Gemini CLI | Switch | ✓ | – | ✓ | ✓ | ✓ | GEMINI.md | ✓ | ✓ |
| Grok Build | Switch | ✓ | – | ✓ | ✓ | ✓ | AGENTS.md | ✓ | ✓ |
| OpenCode | Coexist | – | – | – | ✓ | ✓ | AGENTS.md | ✓ | ✓ |
| OpenClaw | Coexist | – | – | – | – | – | 工作区编辑器 | ✓ | – |
| Hermes | Coexist | – | – | – | ✓ | ✓ | Memory | ✓ | – |
| Pi | Coexist | – | – | – | ✓ | ✓ | AGENTS.md/SYSTEM.md/提示模板 | ✓ | ✓ |
| MiniMax Code | Coexist | – | – | – | ✓ | ✓ | AGENTS.md | ✓ | ✓ |
3. 三种连接模式
- Direct(直连):工具直接连接到 Provider
- Routing(路由):请求本地经过 CC Switch 转发,支持格式转换和故障转移,实现跨 Provider 兼容(比如在 Claude Code 里用 GPT)
- Aggregation(聚合):把多个 Provider 的模型合并成一个选择列表,每次请求路由到对应模型的真实 Provider
4. 集中管理 MCP、Skills、Prompts
一次配置,多工具复用,不需要在每个工具里重复设置同一套 MCP 服务器或 Skills。
5. 会话阅读视图
把原始日志转换成可读的步骤/文件/失败摘要,不需要翻看原始日志文件。
6. 用量与额度追踪
Token 用量、花费、订阅额度直接显示在 Provider 卡片和系统托盘上。
7. 数据存储结构
默认存储在 ~/.cc-switch 目录:
| 文件/目录 | 用途 |
|---|---|
cc-switch.db | SQLite 数据库(Provider、MCP、Prompts、Skills、项目、用量) |
settings.json | 设备级设置 |
backups/ | 自动备份,默认每 24 小时一次,保留最近 10 份 |
skills/ | Skills 目录(可迁移到 ~/.agents/skills) |
backups/live-first-write/ | 安装 CC Switch 前的原始配置快照 |
支持 Windows 上的 WSL 路径配置,以及通过 WebDAV 或 S3 兼容存储做云同步。
深入剖析
"最小侵入"设计:切换只改必要字段
CC Switch 有一条明确的设计原则值得关注:"即使卸载这个应用,你的工具依然能正常工作。"切换 Provider 时,只会改动"关键字段"(endpoint、key、model),而"插件、Hook、MCP,以及你自己添加的注释"保持不动。
如果切换 Provider 时整体覆盖配置文件：
用户手动加的 Hook/插件/注释 → 被覆盖丢失
↑ 每次切换都有破坏现有配置的风险
↑ 用户不敢随意切换，因为代价不可预测
CC Switch 的"最小侵入"做法：
只改动 endpoint/key/model 这几个连接字段
↓ 插件、Hook、MCP、自定义注释原样保留
↑ 卸载 CC Switch 后，工具配置文件依然是完整可用的
↑ 用户可以放心频繁切换，不用担心丢失自定义配置
这个设计选择的意义在于:它把 CC Switch 定位成一个"配置管理的外层工具",而不是"配置文件的唯一真相源"。即便某天不再使用 CC Switch,底层工具的配置依然完整、可独立工作——这降低了用户尝试这个工具的心理门槛,因为"退出成本"被显式地做到了接近零。
Routing 模式:本地格式转换加故障转移
Routing 模式的核心能力是在本地做协议格式转换——在 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 和 Gemini Native 这几种格式之间互相转换,从而实现"在 Claude Code 里用 GPT"这种跨厂商兼容场景。
没有 Routing 时：
Claude Code 只认 Anthropic Messages 格式
↑ 想用 OpenAI 格式的 Provider，工具本身不支持
Routing 模式：
请求先经过本地 CC Switch（默认 http://127.0.0.1:15721）
↓ 格式转换：Anthropic ↔ OpenAI Chat Completions ↔ OpenAI Responses ↔ Gemini Native
↓ 附带断路器（circuit breaker）和 Provider 健康监控做自动故障转移
↓ "Rectifier" 功能自动修复部分上游无法处理的请求
↑ Claude Code 不需要知道背后实际在用哪家 Provider
这个设计把"工具只认一种 API 格式"这个限制,转化成了一个本地代理层能解决的问题——用户不需要等待工具厂商官方支持某个 Provider,只要 CC Switch 支持格式转换,跨厂商组合就是可行的。
Aggregation 模式:致谢 opencodex 的设计借鉴
值得一提的是,CC Switch 的聚合模式设计明确致谢了开源项目 opencodex 的设计思路。这是一个值得肯定的开源协作细节——没有把借鉴来的设计思路据为己有,而是在文档里明确归功于原作者和贡献者。聚合模式本身有一个明确的能力边界:"聚合模式不提供故障转移"——这是文档主动说明的局限,而不是让用户自己踩坑后才发现。此外,Codex 在模型列表变化后需要完整重启才能生效,而 Claude Code 则是即时更新——这种工具间行为差异也被显式记录在文档里。
Switch vs Coexist:两种模式背后的工具差异
CC Switch 没有对所有工具用同一套配置管理策略,而是根据工具自身的能力边界分成 Switch(单一激活)和 Coexist(多 Provider 共存写入)两类。这个划分背后是对每个工具自身配置机制的尊重——像 Claude Code、Codex 这类支持显式切换激活 Provider 的工具用 Switch 模式;而 OpenCode、Hermes 等工具本身的配置机制允许多个 Provider 同时存在于配置文件里,CC Switch 就不强行套用"只能激活一个"的模型,而是采用 Coexist 模式写入。这种"按工具能力适配管理策略"而非"强行统一所有工具行为"的设计,体现了对底层工具差异的尊重,而不是用一套抽象硬套所有场景。
对于 Headless/服务器场景的态度
对于没有 GUI 的无头环境,CC Switch 没有自己做一个 CLI 版本,而是在文档里指向一个独立的社区项目 CC Switch CLI(SaladDay/cc-switch-cli),并明确说明它"与桌面应用共享 ~/.cc-switch 数据目录",但"版本发布是独立的,可能存在版本滞后"。这是一个坦诚的生态边界说明——没有把这个能力硬塞进自己的产品范围,也没有掩盖"两者版本可能不同步"这个潜在的使用风险。
项目地址与资源
官方资源
- 🌟 GitHub:github.com/farion1231/…
- 🌐 官网:ccswitch.io
- 📄 协议:MIT License
- 📝 更新日志:仓库内
CHANGELOG.md
相关资源
- opencodex —— CC Switch 聚合模式的设计灵感来源
- CC Switch CLI —— 面向 Headless/服务器环境的社区 CLI 版本,共享同一数据目录
总结与展望
核心要点回顾
- 一个应用统一管理十款 AI 编程工具的 Provider 配置:告别手动编辑 JSON/TOML/YAML 的碎片化体验
- "最小侵入"设计把退出成本降到接近零:切换只改连接字段,插件/Hook/自定义配置原样保留,卸载后工具依然能独立工作
- 三种连接模式覆盖不同需求:Direct 直连、Routing 本地格式转换加故障转移、Aggregation 多 Provider 模型聚合
- 按工具能力差异化管理策略:Switch(单一激活)/Coexist(多 Provider 共存)分别适配不同工具自身的配置机制
- 坦诚的生态边界意识:聚合模式明确标注"不提供故障转移"、致谢 opencodex 的设计借鉴、Headless 场景指向独立社区 CLI 项目而非自己硬做
适合谁
- 同时使用多款 AI 编程 CLI 的开发者:想要一个统一入口管理所有工具的 Provider 和配置
- 需要频繁切换 Provider 对比效果的用户:一键切换比手动改配置文件效率高得多
- 想要跨厂商混用模型的用户:通过 Routing 模式实现"在 Claude Code 里用 GPT"这类场景
- 需要集中管理 MCP/Skills 的团队:避免在每个工具里重复配置同一套能力
一句话评价
CC Switch 解决的不是"哪个 AI 编程工具更好用"的问题,而是"用好几款工具时,配置管理本身不应该成为负担"这个更朴素但更真实的痛点。
欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。
更多实用知识和有趣产品，欢迎访问我的个人主页
