引言“一键切换 API ProviderMCP、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 → 配置文件是 JSONProvider 信息藏在深层嵌套字段 Codex → 配置文件是 TOML格式完全不同 Gemini CLI → 配置文件是 YAML又是另一套结构 ↑ 每换一次 Provider/API Key/模型都要分别打开对应工具的配置文件手改 ↑ MCP 服务器、Skills、Prompts 要在每个工具里各自配置一份无法共享 CC Switch 的做法 一个桌面应用统一管理十款工具的 Provider 配置 ↓ 一键切换90 预设 ProviderAWS 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 用量、花费、订阅额度,不需要分别打开每个厂商的后台快速开始安装:# macOSbrewinstall--caskcc-switch# macOS 升级brew upgrade--caskcc-switch# Arch Linuxparu-Scc-switch-bin基本使用流程:1. 在侧边栏通过预设或自定义配置添加一个 Provider 2. 通过主界面、系统托盘或项目切换器切换 Provider 3. 切换生效方式因工具而异Claude Code 即时生效其他工具可能需要重启 4. 可选开启 Routing/Aggregation 标签页实现跨格式转换或多 Provider 聚合 5. 通过Apps页面管理已安装 CLI 工具的版本核心特性1. 两种配置管理模式模式含义Switch同一时刻只有一个 Provider 处于激活状态Coexist多个 Provider 同时写入该工具自己的配置文件2. 工具支持能力矩阵工具配置模式本地路由聚合托盘切换MCPSkillsPrompts会话用量统计Claude CodeSwitch✓✓✓✓✓CLAUDE.md✓✓Claude DesktopSwitch仅模型映射–✓––––仅模型映射CodexSwitch✓✓✓✓✓AGENTS.md✓✓Gemini CLISwitch✓–✓✓✓GEMINI.md✓✓Grok BuildSwitch✓–✓✓✓AGENTS.md✓✓OpenCodeCoexist–––✓✓AGENTS.md✓✓OpenClawCoexist–––––工作区编辑器✓–HermesCoexist–––✓✓Memory✓–PiCoexist–––✓✓AGENTS.md/SYSTEM.md/提示模板✓✓MiniMax CodeCoexist–––✓✓AGENTS.md✓✓3. 三种连接模式Direct(直连):工具直接连接到 ProviderRouting(路由):请求本地经过 CC Switch 转发,支持格式转换和故障转移,实现跨 Provider 兼容(比如在 Claude Code 里用 GPT)Aggregation(聚合):把多个 Provider 的模型合并成一个选择列表,每次请求路由到对应模型的真实 Provider4. 集中管理 MCP、Skills、Prompts一次配置,多工具复用,不需要在每个工具里重复设置同一套 MCP 服务器或 Skills。5. 会话阅读视图把原始日志转换成可读的步骤/文件/失败摘要,不需要翻看原始日志文件。6. 用量与额度追踪Token 用量、花费、订阅额度直接显示在 Provider 卡片和系统托盘上。7. 数据存储结构默认存储在~/.cc-switch目录:文件/目录用途cc-switch.dbSQLite 数据库(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:https://github.com/farion1231/cc-switch官网: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 编程工具更好用的问题,而是用好几款工具时,配置管理本身不应该成为负担这个更朴素但更真实的痛点。