CC-Switch：AI 编程 CLI 工具的一体化管理平台

跨平台桌面应用，统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw、Grok Build 与 Hermes Agent 的供应商配置、MCP 服务器、Skills、Prompts 和会话。

一、项目概述

1.1 基本信息

1.2 它是什么

CC Switch 是一款开源的跨平台桌面应用，专为 AI 编程工具的配置管理而设计。它解决了开发者在同时使用多个 AI 编程 CLI 工具（如 Claude Code、Codex、Gemini CLI 等）时面临的配置管理痛点：

• 多个 API Key 和代理地址来回切换，手动改配置文件容易出错
• 不同工具的 MCP 服务器、Skills、Prompts 各自管理，维护成本高
• 切换模型测试效果时需要重启终端、重新认证，效率低下

CC Switch 不是一个简单的"改个 API 地址"的小工具，而是一个全家桶式的管理中心，涵盖了供应商管理、代理路由、MCP 服务器管理、Skills 安装、Prompts 管理、用量统计、会话管理等全方位功能。

1.3 支持的 AI 编程工具

CC Switch 支持 8 种 AI 编程工具的统一管理：

1. Claude Code — Anthropic 的 CLI 编程助手
2. Claude Desktop — Anthropic 的桌面应用
3. Codex — OpenAI 的 CLI 编程工具
4. Gemini CLI — Google 的 CLI 编程工具
5. Grok Build — xAI 的编程工具
6. OpenCode — 开源 AI 编程框架
7. OpenClaw — 开源 AI Agent 框架
8. Hermes Agent — Nous Research 的 AI Agent 框架

每种工具都有专属的供应商预设和配置管理，内置 50+ 个预设配置，覆盖主流 API 中转服务商。

二、核心功能详解

2.1 供应商管理（Provider Management）

这是 CC Switch 最核心的功能——在多个 API 供应商之间一键切换。

• 8 种工具支持，50+ 预设 — 内置大量常用中转节点预设，也支持完全自定义（包括 Kimi、Moonshot、GLM、DeepSeek 等国产模型）
• 通用供应商 — 一份配置可同步到 Claude Code、Codex 和 Gemini CLI，无需重复配置
• 一键切换 — 主界面选择供应商后点击"Enable"即可，系统托盘支持右键快速切换
• 拖拽排序 — 支持拖拽调整供应商优先级
• 导入/导出 — 支持配置的导入导出，方便备份和迁移
• 共享配置片段 — 保存通用配置数据（除 API Key 和端点之外的内容），创建新供应商时自动包含

2.2 本地代理与故障转移（Proxy & Failover）

CC Switch 内置本地代理服务，提供企业级的高可用性保障。

• 本地代理热切换 — 支持格式转换、自动故障转移、熔断器、供应商健康监控和请求修正
• 应用级接管 — 可对 Claude、Codex、Gemini、Grok Build 分别独立代理，精确到单个供应商
• 请求路由 — 统一入口，自动转发到当前激活的供应商
• 健康检查 — 自动检测供应商可用性
• 自动故障转移 — 主供应商异常时自动切换到备用路径

2.3 MCP、Prompts 与 Skills 统一管理

CC Switch 将三大扩展功能整合到统一面板。

MCP 服务器管理： - 统一管理 Claude、Codex、Gemini、Grok Build、OpenCode 和 Hermes 的 MCP 服务器 - 支持 stdio / http / sse 三种传输方式 - 双向同步：CC Switch 中的更改自动同步到对应 CLI 的配置文件 - 支持 Deep Link 导入

Prompts 提示词管理： - 内置 Markdown 编辑器，实时编辑 + 预览 - 跨应用同步（CLAUDE.md / AGENTS.md / GEMINI.md） - 回填保护：编辑当前活跃供应商时，先写 live 文件成功再更新应用主配置 - 可为不同模型/场景准备专属提示词模板，一键应用

Skills 技能管理： - 一键从 GitHub 仓库或 ZIP 文件安装 - 自定义仓库管理 - 支持 Symlink 和文件复制两种安装方式 - 版本管理和批量安装/卸载 - 技能备份：卸载前自动创建备份（保留最近 20 个）

2.4 用量与成本追踪

• 用量仪表盘 — 追踪消费、请求数和 Token 用量
• 趋势图表 — 可视化展示用量趋势
• 详细请求日志 — 记录每次 API 调用
• 自定义模型定价 — 可手动设置每个模型的单价
• 额度展示 — 官方订阅类（Claude/Codex/Gemini/Copilot）自动展示剩余额度

2.5 会话管理器与工作区

• 会话管理器 — 浏览、搜索和恢复跨应用的对话历史
• 工作区编辑器（OpenClaw）— 编辑 Agent 文件（AGENTS.md、SOUL.md 等），支持 Markdown 预览

2.6 系统与平台功能

• 云同步 — 支持自定义配置目录（Dropbox、OneDrive、iCloud、NAS）和 WebDAV 服务器同步
• Deep Link（ccswitch://）— 通过 URL 导入供应商、MCP 服务器、Prompts 和 Skills
• 主题 — 暗色/亮色/跟随系统
• 自动启动 — 开机自启
• 自动更新 — 内置更新器
• 原子写入 — 临时文件 + 重命名模式，防止配置损坏
• 自动备份 — 自动保留最近 10 个版本
• 多语言 — 支持简体中文、繁体中文、英文、日文

三、快速上手指南

3.1 系统要求

3.2 下载与安装

Windows 用户： - 从 GitHub Releases 页面下载 CC-Switch-v{版本号}-Windows.msi 安装包 - 或下载 CC-Switch-v{版本号}-Windows-Portable.zip 便携版

macOS 用户：

方法一：Homebrew 安装（推荐）

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

方法二：手动下载 - 从 Releases 页面下载 CC-Switch-v{版本号}-macOS.dmg（推荐）或 .zip - macOS 版本经过 Apple 代码签名和公证，可直接安装打开

Arch Linux 用户：

paru -S cc-switch-bin

Linux 用户： 从 Releases 页面下载对应格式： - CC-Switch-v{版本号}-Linux.deb — Debian/Ubuntu - CC-Switch-v{版本号}-Linux.rpm — Fedora/RHEL/openSUSE - CC-Switch-v{版本号}-Linux.AppImage — 通用格式

3.3 基本使用流程

步骤 1：添加供应商 - 打开 CC Switch，点击"Add Provider" - 选择预设配置或创建自定义配置 - 填入 API Key 和基地址

步骤 2：切换供应商 - 主界面方式：选择供应商 → 点击"Enable" - 系统托盘方式：右键点击供应商名称（即时生效）

步骤 3：使其生效 - 重启终端或对应 CLI 工具使更改生效 - 例外：Claude Code 支持热切换，无需重启

步骤 4：返回官方登录 - 从预设列表添加"官方登录"供应商 - 重启 CLI 工具后执行登录/OAuth 流程 - 之后可在官方和第三方供应商之间自由切换

3.4 MCP、Prompts、Skills 与会话管理

• MCP：点击"MCP"按钮 → 通过模板或自定义配置添加服务器 → 切换每应用同步
• Prompts：点击"Prompts" → 用 Markdown 编辑器创建预设 → 激活以同步到 live 文件
• Skills：点击"Skills" → 浏览 GitHub 仓库 → 一键安装到支持的 App
• Sessions：点击"Sessions" → 浏览、搜索和恢复跨应用的对话历史

3.5 数据存储位置

四、技术架构

4.1 整体架构

┌─────────────────── Frontend (React + TS) ───────────────────┐
│   Components (UI)    │    Hooks (逻辑)    │  TanStack Query  │
└─────────────────────────┬───────────────────────────────────┘
                          │ Tauri IPC
┌─────────────────── Backend (Tauri + Rust) ──────────────────┐
│   Commands (API)    │   Services (逻辑)   │  Models/Config  │
└─────────────────────────────────────────────────────────────┘

4.2 核心设计模式

• SSOT（单一数据源）：所有数据存储在 ~/.cc-switch/cc-switch.db (SQLite)
• 双层存储：SQLite 存储 可同步数据，JSON 存储 设备级设置
• 双向同步：切换时写入 live 文件，编辑活跃供应商时从 live 文件回填
• 原子写入：临时文件 + 重命名模式防止配置损坏
• 并发安全：Mutex 保护的数据库连接避免竞态条件
• 分层架构：Commands → Services → DAO → Database 清晰分离

4.3 关键组件

4.4 技术栈

前端： - React 18 + TypeScript + Vite - TailwindCSS 3.4 - TanStack Query v5（缓存/同步） - react-i18next（国际化） - react-hook-form + zod（表单验证） - shadcn/ui（UI 组件库） - @dnd-kit（拖拽排序）

后端： - Tauri 2.8 + Rust - serde（序列化） - tokio（异步运行时） - thiserror（错误处理） - tauri-plugin-updater/process/dialog/store/log

测试： - vitest（前端测试框架） - MSW（Mock Service Worker，模拟 Tauri API） - @testing-library/react（组件测试）

五、开发指南

5.1 环境要求

• Node.js 18+
• pnpm 8+
• Rust 1.85+
• Tauri CLI 2.8+

5.2 开发命令

# 安装依赖
pnpm install

# 开发模式（热重载）
pnpm dev

# 类型检查
pnpm typecheck

# 格式化代码
pnpm format

# 检查代码格式
pnpm format:check

# 运行前端单元测试
pnpm test:unit

# 监听模式运行测试
pnpm test:unit:watch

# 构建应用
pnpm build

# 构建调试版本
pnpm tauri build --debug

5.3 Rust 后端开发

cd src-tauri

# 格式化 Rust 代码
cargo fmt

# 运行 clippy 检查
cargo clippy

# 运行后端测试
cargo test

# 运行特定测试
cargo test test_name

# 启用 test-hooks 特性运行测试
cargo test --features test-hooks

5.4 项目结构

├── src/                        # 前端 (React + TypeScript)
│   ├── components/
│   │   ├── providers/          # 供应商管理
│   │   ├── mcp/                # MCP 面板
│   │   ├── prompts/            # Prompts 管理
│   │   ├── skills/             # Skills 管理
│   │   ├── sessions/           # 会话管理器
│   │   ├── proxy/              # 代理模式面板
│   │   ├── openclaw/           # OpenClaw 配置面板
│   │   ├── settings/           # 设置
│   │   ├── deeplink/           # Deep Link 导入
│   │   ├── env/                # 环境变量管理
│   │   ├── universal/          # 跨应用配置
│   │   ├── usage/              # 用量统计
│   │   └── ui/                 # shadcn/ui 组件库
│   ├── hooks/                  # 自定义 hooks（业务逻辑）
│   ├── lib/
│   │   ├── api/                # Tauri API 包装（类型安全）
│   │   └── query/              # TanStack Query 配置
│   ├── locales/                # 翻译 (zh/zh-TW/en/ja)
│   ├── config/                 # 预设 (供应商/MCP)
│   └── types/                  # TypeScript 定义
├── src-tauri/                  # 后端 (Rust)
│   └── src/
│       ├── commands/           # Tauri 命令层（按域分）
│       ├── services/           # 业务逻辑层
│       ├── database/           # SQLite DAO 层
│       ├── proxy/              # 代理模块
│       ├── session_manager/    # 会话管理
│       ├── deeplink/           # Deep Link 处理
│       └── mcp/                # MCP 同步模块
├── tests/                      # 前端测试
└── assets/                     # 截图和素材

六、常见问题（FAQ）

Q1：CC Switch 支持哪些 AI 工具？

支持 8 种工具：Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw 和 Hermes。每种工具都有专属的供应商预设和配置管理。

Q2：切换供应商后需要重启终端吗？

大多数工具需要重启终端或 CLI 工具才能生效。例外是 Claude Code，它支持供应商数据的热切换，无需重启。

Q3：切换供应商后插件配置消失了怎么办？

CC Switch 提供"共享配置片段"功能。进入"Edit Provider" → "Shared Config Panel" → 点击"Extract from Current Provider"保存所有通用数据。创建新供应商时勾选"Write Shared Config"（默认启用），即可包含插件数据。

Q4：macOS 安装需要注意什么？

CC Switch 的 macOS 版本经过 Apple 代码签名和公证，可直接下载安装。推荐使用 .dmg 安装包。

Q5：为什么不能删除当前活跃的供应商？

CC Switch 遵循"最小侵入"设计原则——即使卸载应用，CLI 工具也会继续正常工作。系统始终保留一个活跃配置，因为删除所有配置会导致对应 CLI 工具不可用。如果很少使用某个 CLI 工具，可以在设置中隐藏它。

Q6：如何切换回官方登录？

从预设列表添加官方供应商，切换到它后运行 Log out / Log in 流程。之后可在官方和第三方供应商之间自由切换。Codex 支持在不同官方供应商之间切换，方便管理多个 Plus 或 Team 账号。

Q7：Linux (Wayland + NVIDIA) 点击无响应？

AppImage 默认强制使用 GDK_BACKEND=x11 (XWayland)，在新版 Wayland + NVIDIA 环境可能导致点击失效。启动时可添加环境变量切回原生 Wayland：

CC_SWITCH_GDK_BACKEND=wayland ./CC-Switch-*.AppImage

七、适用人群

CC Switch 强烈推荐以下用户使用：

• 重度使用 Claude Code / Codex / Gemini CLI 的开发者
• 经常测试不同中转节点、不同模型性价比的人
• 需要管理大量自定义 Skills 和 Prompt 模板的 AI 编程玩家
• 讨厌每次切换模型都要手动改 JSON 文件的强迫症患者
• 跨平台办公（Windows + macOS + Linux）的程序员
• 使用多个 AI 模型/多个渠道并行开发的人

八、与同类工具对比

九、总结

CC Switch 是目前唯一同时支持 8 大主流 AI 编程 CLI 工具的统一管理平台。它基于 Tauri + Rust 构建的桌面原生应用，轻量高效，功能全面：

• 从供应商切换到 MCP/Skills/Prompts 管理的一站式解决方案
• 内置本地代理和故障转移，提供企业级高可用性
• 用量追踪和成本统计让 API 开销一目了然
• 跨平台支持，完全开源免费
• 社区活跃，作者维护极其积极，持续迭代更新

如果你每天都在使用 AI 编程工具，且不止用一个模型或一个渠道，CC Switch 几乎是必装工具。它让你告别频繁修改配置文件的痛苦，专注于编码本身。

参考链接

• GitHub 仓库：https://github.com/farion1231/cc-switch
• 官方网站：https://ccswitch.io
• 中文文档：https://ccswitch.co/zh/docs.html
• 下载地址：https://github.com/farion1231/cc-switch/releases
• 用户手册：https://github.com/farion1231/cc-switch/tree/main/docs/user-manual
• Star 历史：https://star-history.com/#farion1231/cc-switch

本文档基于 cc-switch 项目 GitHub README 和公开资料整理，最后更新于 2026 年 7 月 22 日。