引言
"一键切换 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. 两种配置管理模式
2. 工具支持能力矩阵
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 目录:
支持 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 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。
更多实用知识和有趣产品，欢迎访问我的个人主页
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
Introduction
"One key to switch API Profider, MCP, Skills, Prompts centralized management - no more manual editing of JSON/TOML/YAML configuration file."
This is part 234 of the "One Open Source Project a Day" series. Today's project is CC Switch.
Now using several AI programming tools at the same time is normal -- Claude Code runs a project, Codex runs another, and occasionally cuts to Gemini CLI or Grok Build. The problem is that each of these tools has a configuration format: Claude Code uses a JSON structure, Codex uses TOML, Gemini CLI, and another YAML -- each time you change Provider, change API Key, change the model, you turn it into the configuration file of the corresponding tool, and the MCP server and Skills have to have one in each tool.
CC Switch has made this a unified desktop application: a tool to manage 10 AI programming tools (Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenClaw, Hermes, Pi, Mini Max Code) with Provider configurations that support single-key switching, 90+Provider presets, and local requests for format conversion routes (Routing) and multiple Provider models.
142.8k Stars, MIT Agreement, based on Tauri 2 + Rust + React 18, is currently one of the largest open-source projects in this track.
What will you learn?
- CC Switch how to harmonize the configuration management of the 10 tools using the Switch/Coexist model
- Specific differences and applicable scenarios between Direct, Routing, Aggregation
- "Minimum Intrusion" design concept: Switch Provider, why don't you break your manual plugs and Hook?
- Format conversion and failure transfer mechanism for local requests
- Data storage design: ~/.cc-switch directory structure and cloud synchronization
Pre-knowledge
- Used at least one AI programming CLI tool (Claude Code, Codex, Gemini CLI, etc.)
- Understanding the basic concepts of API Production, Base URL, API Key
- Options: Understanding the basic uses of MCP would make it easier to understand centralized management
Project background
Project Profile
The official location of CC Switch is: "The Full Desktop Assistant for Cross Platform for Claude Code, Codex, OpenCode, OpenClaw, Grok Build and Hermes Age." More fully put, "Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenClaw, Hermes Agent, Pi and Mini Max Code" Core value proposition: "One key switch to API Projecter, MCP, Skills, Prompts centralized management - no manual editing of JSON/TOML/YAML configuration file"
Team and project information
- By Jason Young
- Protocol: MIT License
- Technical warehouse: Tauri 2, Rust, React 18, TypeScript, SQLite
Other Organiser
Project data
- ⭐ GitHub Stars:142,800+
- 🍴 Forks:9,500+
- 👀 Watchers:264
- Protocol: MIT
Main functions
Solve what?
Multi-tool management without CC Switch:
Claude Code configuration file is JSON,Provider information hidden in deep embedded field
Codex → Profile is TOML in completely different formats
Gemini CLI → Profile is YAML and another set of structures
Every change in Provider/API Key/ Model, each configuration filer opens the corresponding tool Change
↑MCP server, Skills, Prompts to configure one in each tool and not share
CC Switch:
A desktop application that centrally manages the Provider configuration of 10 tools
↓ One-key switch, 90+ presetProvider (AWS Bedrock, NVIDIA NIM, community transit, etc.)
MCP, Skills, Prompts centrally manage one configuration, multiple tools reuse
↑ Switch only field (endpoint/key/model)
Plugin, Hook, custom configuration remains unchanged
Use scene
- Developer of multiple AI programming CLI
- Wants to centrally manage Provider and API Key instead of cutting back and forth between the configuration files of each tool Switch
- Users who need frequent switching of tests between multipleProviders
- Compare the effects of different models/Provider with one key toggle instead of manually changing configuration files
- Team that wants to use MCP server configuration across tools
- Do not want the same MCP server in Claude Code, Codex, Gemini CLI
- to use GPT in Claude Code, or to mix different manufacturers' models.
- Local format conversion through Routing mode to make cross-Provider compatible
- Multiple Provider users to track usage and cost
- Directly view Token usage, spending, subscription to quota on Provider cards and system trays without having to open the back of each manufacturer separately
Fast start.
Installation:
# macOS
brew install --cask cc-switch
# MacOS Upgrade
brew upgrade --cask cc-switch
# Arch Linux
paru -S cc-switch-bin
Basic usage process:
Add aProvider to the sidebar by preset or custom configuration
2. Switches through main interfaces, system trays or project switches
3. The mode of entry into force varies from tool to tool: Claude Code is effective immediately and other tools may need to be restarted
4. Optional: Opening the Routing/Aggregation tab to achieve cross-formatization or multipleProvider aggregation
5. Manage the installed version of the CLI tool through "Apps" page
Core characteristics
1. Two configuration management models
2. Tool support capacity matrix
Three modes of connection
-Direct (Front connection): Tools are connected directly toProvider
-Routing: Request local forwarding via CC Switch, support format conversion and failure transfer, cross-Provider compatibility (e.g. using GPT in Claude Code)
-Aggregation (aggregation): Merge multiple Provider models into a selection list, each requesting a path to the true of the corresponding model
Centralized management MCP, Skills, Prompts
One configuration, multiple tool reuse, does not need to duplicate the same MCP server or Skills set in each tool.
5. Session reading view
Converts the original log into a readable step/file/failed summary without going through the original log file.
6. Usage versus quota tracking
Token uses, spends, subscribes to quota directly on Provider cards and system trays.
7. Data storage structure
Default stored in ~/.cc-switch directory:
Supports the WSL path configuration on Windows, as well as cloud synchronization through WebDAV or S3 compatible storage.
In-depth Analysis
Design of Minimum Invasion: Switch to field only
CC Switch has a clear design principle that deserves attention: "Even if you unload this application, your tools will work. "Toggle Provider will only change "Key field" (endpoint, key, model), while "Plugins, Hook, MCP, and your own added notes" will remain unchanged.
If the configuration file is overwrited when switching toProvider:
The user manually added Hook/ Plugin/ Comment Zoom Overrided Lost
Each switch risks undermining the current configuration.
Users are afraid to switch because the cost is unpredictable
CC Switch's "minimal intrusion" approach:
Change only endpoint/key/model these connections to field
↓ Plugin, Hook, MCP, Custom Note as retained
The tool configuration file remains fully available after unmounting CC Switch
↑ User can easily switch and not worry about losing the custom configuration
The point of this design choice is that it places CC Switch as an "exterior tool for configuration management" rather than "the only source of information for configuration documents." Even if CC Switch is not used one day, the bottom tool is fully configured and able to work on its own -- this lowers the psychological threshold for users to try the tool, because the "exit cost" is visibly close to zero.
Routing mode: local format conversion and failure transfer
The core competencies of the Routing mode are local protocol conversions - cross-producer compatibility scenarios such as "GPT" in Claude Code by switching between these formats.
When no Routing:
Claude Code only recognizes anthropic Messages format
Provider in Open AI format, the tool itself is not supported
Routing mode:
Request to go through local CC Switch (default http://127.0.0.115721).
↓ Format conversion: Anthropic ↔ Open AI Chat Rules ↔ Open AI Reponses ↔ Gemini Native
circuit breaker and Provider health surveillance for automatic failure transfer
↓Rectifier Auto-rehabilitation Upstream
Claude Code doesn't need to know what's actually behind it.
The design changed the limit of "tools only in an API format" to a local proxy level solution -- – Users do not have to wait for the tool manufacturer to officially support a Provider, and cross-producer combinations are feasible as long as CC Switch supports a format conversion.
Aggregation mode: thanks to opencodex design
It is worth mentioning that CC Switch's aggregate model design clearly acknowledges the design thinking of Opensource Project Opencodex. This is a positive detail of open-source collaboration — not taking the design ideas that have been drawn on for itself, but being clearly attributed in the document to the original author and contributor. The polymer mode itself has a clear capability boundary: "Aggregation mode does not provide fault transfer" -- This is the limitation of the document ' s own initiative, rather than being discovered after the user has stepped on the pit itself. Besides, Codex needs to be fully restarted after the model list changes, while Claude Code is up to date -- This difference in behavior between tools is also recorded in the document.
Switch vs Coexist: the tools behind the two models
CC Switch does not use the same set of configuration management strategies for all tools, but rather divides them into two categories, Switch (single activation) and Coexist (multi-Provider coexistence). Behind this division is respect for each tool's own configuration mechanisms - tools such as Claude Code, Codex, which support a visible switch to activate Provider, use the Switch model; and tools such as OpenCode, Hermes, whose own configurations allow multiple Providers to be present in the configuration file, CC Switch does not force "activate" models, but uses the Coexist model. This design of "tool-compatible management strategy" rather than "forced harmonization of all tools" reflects respect for the differences in the bottom tools rather than an abstract set of all scenarios.
Attitude towards the Headless/server scene
For a headless environment without GUI, CC Switch does not make a CLI version on its own, but points to an independent community project CC Switch CLI (SaradDay/cc-switch-cli) in the document and makes it clear that it "shared with desktop applications ~/.cc-switch data directories", but "version publish is independent and may have a late version". This is a candid ecological boundary statement — it does not push this capacity into its own product range, nor does it mask the potential use risk of "the two versions may not be synchronized".
Project address and resources
Official resources
- 🌟 GitHub:github.com/farion1231/…
cc Official: ccswitch.io
Agreement: MIT License
- Update log: CHANGELOG.md in warehouse
Related resources
- Opencodex - a design inspiration for CC Switch aggregation mode
- CC Switch CLI - Community CLI version for Headless/server environment, sharing the same data directory
Summary and outlook
Review of core elements
- A Provider configuration with the application of the Integrated Management of 10 AI Programming Tools: Goodbye manual editing of JSON/TOML/YAML
- "Minimum Invasion" designs to reduce exit costs to close to zero: Switch only to field, Plugin/Hook/Customise Configuration as it is, unmounted tools still work independently
- Three modes of connection cover different needs: Direct Straight, Routing Local Format Transfer and Aggregation MultiProvider Model Aggregation
- Management strategy for differentiated tools: Switch/Coexist (Multi-Provider Coexistence) adapts its own configuration mechanisms to different tools
- Open ecological boundary awareness: Convergence model clearly labels "no trouble transfer", thanks to opencodex design, Headless scene points to independent communities, CLI project, not hard work.
For who?
- Developer of multiple AI programming CLI: Provider and configuration for a single access management tool
- Users who need frequent switching of the Provider comparison: a key switch is much more efficient than manual configuration files
- Users of cross-producer hybrid models: through Routing mode to achieve scenarios like "GPT" in Claude Code
- MCP/Skills teams need to be centrally managed: avoid reconfiguring the same set of capabilities in each tool
A word evaluation
CC Switch does not solve the problem of which AI programming tool is better used, but rather the more simple, but more real, painful point of "Settlement management should not be a burden in itself" when using several tools.
Welcome to PrimeSkills - a well-planned AI Agent and skills market, all of which has been validated by real enterprise-level workflow. There's no twitch, there's only something that really works.
More practical knowledge and interesting products. Welcome to my home page.
Auto-fetched and translated by AI Atlas. All rights belong to the original author.