CC Switch 入门：统一管理 Claude Code、Codex、Gemini CLI 等多 AI 工具的跨平台桌面助手

CC Switch 是一款专为使用 AI 编程工具的开发者设计的跨平台桌面应用，核心目标是把 Claude Code、Claude Desktop、Codex、Gemini CLI、OpenCode、OpenClaw、Hermes 等工具各自独立的配置文件统一到同一界面下管理。读完本文，你将了解它解决了哪些多供应商开发痛点、覆盖哪些应用与平台，以及它在供应商管理、MCP/Prompts/Skills 扩展和本地代理高可用三方面的能力边界，并看到这些能力在源码中的对应实现。

定位：一个入口管理所有 AI 编程工具的供应商配置

CC Switch 是一款跨平台桌面应用。它的定位不是 AI 编程工具本身，而是这些工具背后的"配置中枢"：当你同时使用多个 AI 编程助手、且在不同 API 供应商（官方直连或中转服务）之间切换时，它把原本散落各处、格式各异的手动改配置过程收敛为一次点击。

从源码结构看，受管应用清单定义在后端的 AppType 枚举中（见 app_config.rs），当前版本（v3.20.0）共包含 9 种客户端类型：Claude、ClaudeDesktop、Codex、Gemini、GrokBuild、OpenCode、OpenClaw、Hermes 和 Pi。相比用户文档中的 7 项列表，源码中还能看到对 Grok Build 与 Pi 客户端的支持，这也是项目描述中提到的 "Grok Build & Hermes Agent" 的落点。

它解决的四类痛点

在多 AI 工具并用的日常开发中，典型痛点有四类，CC Switch 分别给出了对应方案：

痛点	具体表现	CC Switch 的应对
多供应商切换麻烦	换一家 API 供应商（官方或中转服务商）就要手动改配置文件	供应商列表 + 一键切换，支持预设模板快速添加常用供应商
配置分散难管理	各工具有独立配置文件，路径与格式各不相同（JSON、TOML 等）	统一界面读写各应用的原生配置文件，跨应用共享供应商配置
无法监控用量	不知道 API 调用了多少次、花了多少钱	本地代理记录请求日志，做 Token 用量追踪与成本估算
服务不稳定	单一供应商故障导致整个工作流中断	自动故障转移（Failover）+ 熔断器机制

其中"配置分散"这一点，在 config.rs 中有清晰的代码印证：Claude Code 的主配置位于 ~/.claude/settings.json（并兼容旧命名 claude.json），MCP 配置位于 ~/.claude.json，而 CC Switch 自身的数据目录为 ~/.cc-switch。应用同时支持通过设置覆盖上述路径，以便多 Profile 场景下管理不同配置目录。

支持的应用及其写入模式

官方文档（1.1-introduction.md）列出的受管应用如下：

应用	说明
Claude Code	Anthropic 官方的 AI 编程助手
Claude Desktop	Claude 桌面应用，支持官方登录与第三方 3P profile
Codex	OpenAI 的代码生成工具
Gemini CLI	Google 的 AI 命令行工具
OpenCode	开源 AI 编程终端工具
OpenClaw	开源 AI 助手（多供应商网关）
Hermes	Hermes Agent，支持供应商、MCP、Skills 和 Memory 管理

值得注意的是，从源码结构看，不同应用的供应商"切换"语义并不相同。AppType 上定义了两个关键方法（见 app_config.rs）：

• Switch 模式（覆盖式）：Claude、Codex、Gemini、GrokBuild。切换供应商时，只有当前激活供应商的凭据被写入该工具的原生配置文件，配置文件中始终只保留"当前在用"的一份供应商信息。
• Additive 模式（共存式）：OpenCode、OpenClaw、Hermes、Pi。多个供应商同时写入该工具的本地原生配置（is_additive_mode() 返回 true），各自可以独立启用/禁用，互不覆盖。

此外，supports_local_proxy() 表明本地代理服务目前面向 Claude、Codex、Gemini、GrokBuild 四类客户端生效，其余客户端的供应商配置则直接写入各自的原生配置文件。理解这一区分，有助于判断某项功能（如代理日志、故障转移）对你所用的具体工具是否可用。

核心功能一：供应商管理

供应商管理是 CC Switch 的主体能力，包含六个要点：

• 一键切换多个 API 供应商配置：每个应用维护一份供应商列表，切换时由 Rust 后端读取供应商数据并原子性地改写目标工具的原生配置文件；
• 预设模板：内置多家常见供应商的预设（如 claudeProviderPresets.ts、codexProviderPresets.ts、geminiProviderPresets.ts 等配置文件），填好 API Key 即可快速添加，无需手写完整配置；
• 统一供应商、跨应用共享：同一供应商的凭据信息可在不同受管应用间复用；
• Claude Desktop 专项支持：支持第三方供应商接入、直连模式与模型映射（前端对应实现见 claudeDesktopProviderPresets.ts 及相关表单组件）；
• 用量查询与余额显示：读取供应商侧用量/余额接口并在卡片上展示；
• 端点速度测试：对供应商端点做连通性与速度探测，辅助选择最优端点。

供应商配置写入的可靠性值得单独一提。后端对配置文件的写入采用"先写临时文件、再原子替换"的策略（见 config.rs 中的 atomic_write）：写入过程中目标文件始终处于完整状态，避免写一半崩溃导致配置文件损坏；在 Windows 上会优先使用 ReplaceFileW 并带重试回退，包含对 WSL UNC 路径的专门处理。同时，JSON 输出前会递归按键名字母序排序（sort_json_keys），保证同一份逻辑配置无论编辑顺序如何，落盘字节一致，便于 diff 与版本对比。相关测试用例（如 atomic_write_replaces_existing_file）位于同一文件内，可验证"替换成功且无临时文件残留"等契约。

核心功能二：MCP、Prompts 与 Skills 扩展

除供应商外，CC Switch 把三类扩展资源也纳入统一管理：

• MCP 服务器：管理 Model Context Protocol 服务器配置，扩展 AI 工具可访问的外部能力。Claude 的 MCP 配置写入 ~/.claude.json（路径解析逻辑见 config.rs），前端提供表单与向导式添加（McpFormModal.tsx、McpWizardModal.tsx），内置常用 MCP 预设（mcpPresets.ts）；
• Prompts：管理系统提示词预设，按客户端分开维护、快速切换不同场景。后端数据结构 PromptRoot（见 app_config.rs）为 claude、claude-desktop、codex、gemini、grokbuild、opencode、openclaw、hermes 各自维护独立的 Prompt 集合，互不干扰；
• Skills：安装和管理技能扩展，支持按仓库管理技能（前端入口见 RepoManagerPanel.tsx）。

核心功能三：本地代理与高可用

当把 Claude Code、Codex 等工具的流量指向 CC Switch 的本地代理后，就获得了日志、统计与高可用能力，包括四项：

1. 本地代理服务与请求日志：代理转发请求并记录日志与用量统计。代理核心实现在 src-tauri/src/proxy/ 目录下，包含请求转发（forwarder.rs）、SSE 流处理（sse.rs）、用量统计（usage/ 子目录）等模块；

2. 自动故障转移：主供应商失败时自动切换到备用供应商，由 failover_switch.rs 与 provider_router.rs 实现路由与切换决策，前端通过 FailoverToggle.tsx、AutoFailoverConfigPanel.tsx 配置开关与策略；

3. 熔断器机制：防止频繁重试已失败的供应商。实现见 circuit_breaker.rs，采用经典的三态模型：

   • Closed（关闭）：正常工作；
   • Open（打开）：熔断激活，拒绝向该供应商发请求；
   • HalfOpen（半开）：允许部分探测请求通过，成功达到阈值后恢复 Closed。

   从源码的 Default 实现可以看到默认参数：连续失败 4 次（failure_threshold）打开熔断；打开后 60 秒（timeout_seconds）进入半开试探；半开状态下连续成功 2 次（success_threshold）恢复关闭；错误率超过 60%（error_rate_threshold）且总请求数达到 10 次（min_requests）时也会触发熔断。该模块还支持配置热更新（update_config 不重置统计状态）；

4. Token 用量追踪与成本估算：逐请求统计 Token 消耗并做成本估算，前端用量看板（UsageDashboard.tsx）展示趋势、按模型/供应商的统计与请求明细。

支持的平台

官方支持矩阵如下（与 README.md 中的系统要求一致）：

• Windows 10 及以上；
• macOS 12 (Monterey) 及以上；
• Linux Ubuntu 22.04+ / Debian 11+ / Fedora 34+（x64 / ARM64）。

从源码的 Cargo.toml 可以看到平台适配的工程细节：Linux 依赖 webkit2gtk 2.16+（对应 Tauri 2 的 WebKitGTK 要求）、Windows ARM64 下 rquickjs 启用 bindgen 特性、macOS 使用 objc2 系列库做系统集成，且 macOS 构建产物经 Apple 代码签名与公证，可直接安装。

技术架构与数据存储

CC Switch 使用现代化的桌面端技术栈构建（版本号以当前仓库 package.json 与 Cargo.toml 中的 3.20.0 为准）：

• 前端：React 18 + TypeScript 5.3 + Tailwind CSS 3.4，配合 TanStack Query 管理数据请求、Radix UI 组件库与 shadcn 风格的 UI 层（见 src/components/ui/），i18next 提供多语言；
• 后端：Tauri 2（依赖 tauri 2.8.2）+ Rust（要求 Rust 1.85+，见 rust-toolchain.toml）。代理层使用 axum/hyper/reqwest（rustls）处理 HTTP 转发，rquickjs 内嵌 JS 引擎用于用量脚本等场景，toml/toml_edit 处理 Codex 等工具的 TOML 配置；
• 数据存储：SQLite（rusqlite bundled，存放供应商、MCP、Prompts 等结构化数据，数据库位于 ~/.cc-switch/cc-switch.db）+ JSON（~/.cc-switch/config.json 等设备设置），数据库表结构与迁移逻辑见 src-tauri/src/database/。

这套"Web 前端 + Rust 系统层"的架构带来的结果是：三个平台上的界面与交互一致；配置读写、代理转发等重活在本地原生进程完成；所有数据（含 API Key）只落在用户本机，不经过任何第三方服务端。

下一步

本文是 用户手册 入门篇的第一篇（软件介绍），建议按以下顺序继续阅读：

• 1.2 安装：各平台的具体下载与安装方式；
• 1.3 界面介绍：主界面各区域的功能说明；
• 1.4 快速上手：从添加第一个供应商到完成首次切换；
• 1.5 设置：应用目录、语言、主题等全局设置。

若需要深入某一功能，可直接查看对应源码目录：代理与高可用见 src-tauri/src/proxy/，应用与配置解析见 src-tauri/src/app_config.rs 与 src-tauri/src/config.rs，数据库见 src-tauri/src/database/。