CC Switch 完全指南：统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw

摘要：CC Switch 是一个跨平台的桌面 All-in-One 助手工具，专为管理多个 AI 编码 CLI 工具而设计。它提供统一的提供商管理、MCP 服务器配置、Skills 安装、代理故障转移等功能，让你无需手动编辑配置文件即可在多个 AI 工具间快速切换。本文将详细介绍 CC Switch 的安装、配置和高级用法。

---

一、CC Switch 是什么？

1.1 问题背景

现代 AI 编程依赖多个 CLI 工具：

• Claude Code – Anthropic 的编码助手
• Codex – OpenAI 的编码助手
• Gemini CLI – Google 的编码助手
• OpenCode – 开源编码助手
• OpenClaw – 可扩展的 AI 代理框架

痛点：

• ❌ 每个工具有不同的配置文件格式（JSON、TOML、.env）
• ❌ 切换 API 提供商需要手动编辑配置文件
• ❌ MCP 服务器和 Skills 配置分散在多处
• ❌ 没有统一的方式管理多个工具
• ❌ 配置文件容易出错或损坏

1.2 CC Switch 解决方案

CC Switch 是一个统一的桌面应用，让你：

• ✅ 一个应用管理五个工具 – Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw
• ✅ 无需手动编辑 – 50+ 内置提供商预设，一键导入和切换
• ✅ 统一 MCP 和 Skills 管理 – 一个面板管理四个应用的扩展
• ✅ 系统托盘快速切换 – 无需打开完整应用即可切换提供商
• ✅ 云同步 – 通过 Dropbox、OneDrive、iCloud 或 WebDAV 同步配置
• ✅ 跨平台 – Windows、macOS、Linux 原生桌面应用
• ✅ 内置工具 – 登录确认、签名绕过、插件同步等实用功能

1.3 核心特性

特性	说明
5 个 CLI 工具支持	Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw
50+ 预设提供商	AWS Bedrock、NVIDIA NIM、社区中继等
一键切换	主界面或系统托盘快速切换
MCP 统一管理	4 个应用的双向同步
Prompts 管理	Markdown 编辑器，跨应用同步
Skills 安装	从 GitHub 仓库一键安装
本地代理	格式转换、自动故障转移、熔断器
使用统计	支出、请求、Token 追踪
会话历史	浏览、搜索、恢复对话历史
云同步	自定义配置目录，WebDAV 服务器同步

---

二、安装指南

2.1 系统要求

平台	要求
Windows	Windows 10 及以上
macOS	macOS 12 (Monterey) 及以上
Linux	Ubuntu 22.04+ / Debian 11+ / Fedora 34+

2.2 Windows 安装

方法 1：MSI 安装程序（推荐）

1. 从 Releases 下载最新版 .msi 文件
2. 双击运行安装程序
3. 按照提示完成安装

方法 2：便携版

1. 下载 .zip 便携版
2. 解压到任意目录
3. 运行 CC-Switch.exe

2.3 macOS 安装

方法 1：Homebrew（推荐）

# 添加 tap
brew tap farion1231/ccswitch

# 安装
brew install --cask cc-switch

# 更新
brew upgrade --cask cc-switch

方法 2：手动下载

1. 从 Releases 下载 .zip 文件
2. 解压并移动到应用程序文件夹

⚠️ 注意：macOS “身份不明开发者”警告

由于开发者尚未注册 Apple Developer 账户，首次启动时可能会看到警告：

解决方法：

1. 关闭警告对话框
2. 打开 系统设置 → 隐私与安全性
3. 点击 “仍要打开”
4. 之后应用即可正常打开

2.4 Linux 安装

方法 1：使用 paru（Arch Linux，推荐）

paru -S cc-switch-bin

方法 2：下载对应包

从 Releases 下载：

• CC-Switch-v{version}-Linux.deb – Debian/Ubuntu
• CC-Switch-v{version}-Linux.rpm – Fedora/RHEL/openSUSE
• CC-Switch-v{version}-Linux.AppImage – 通用
• CC-Switch-v{version}-Linux.flatpak – Flatpak

安装示例：

# Debian/Ubuntu
sudo dpkg -i CC-Switch-v{version}-Linux.deb

# Fedora/RHEL
sudo rpm -i CC-Switch-v{version}-Linux.rpm

# AppImage（通用）
chmod +x CC-Switch-v{version}-Linux.AppImage
./CC-Switch-v{version}-Linux.AppImage

# Flatpak
flatpak install --user ./CC-Switch-v{version}-Linux.flatpak
flatpak run com.ccswitch.desktop

---

三、快速开始

3.1 首次启动

1. 启动应用
   • Windows：从开始菜单或桌面快捷方式
   • macOS：从应用程序文件夹
   • Linux：从应用菜单或命令行
2. 导入现有配置（可选）
   • 首次启动时，可以手动导入现有 CLI 工具配置作为默认提供商
3. 添加第一个提供商
   • 点击 “Add Provider” 按钮
   • 选择预设或创建自定义配置

3.2 添加提供商

方法 1：使用预设（推荐）

1. 点击 “Add Provider”
2. 从预设列表中选择一个提供商
3. 输入 API Key
4. 点击 “Save”

方法 2：自定义配置

1. 点击 “Add Provider”
2. 选择 “Custom Provider”
3. 填写配置：
   • 名称
   • API 端点
   • API Key
   • 模型映射（可选）
4. 点击 “Save”

支持的提供商类型：

• 官方提供商（Anthropic、OpenAI、Google 等）
• 云服务商（AWS Bedrock、NVIDIA NIM 等）
• 社区中继（多个第三方 API 服务）

3.3 切换提供商

方法 1：主界面切换

1. 在主界面选择提供商卡片
2. 点击 “Enable” 按钮
3. 重启终端或 CLI 工具（Claude Code 除外，支持热切换）

方法 2：系统托盘快速切换

1. 点击系统托盘图标
2. 直接点击提供商名称
3. 立即生效（无需打开完整应用）

注意：

• 大多数工具需要重启终端或 CLI 才能生效
• Claude Code 支持热切换，无需重启

3.4 切换回官方登录

如果需要切换回官方登录流程：

1. 从预设列表添加 “Official Login” 提供商
2. 切换到该提供商
3. 重启 CLI 工具
4. 按照 CLI 工具的登录/OAuth 流程操作
5. 之后可以在官方和第三方提供商间自由切换

---

四、核心功能详解

4.1 提供商管理

添加提供商

Add Provider → 选择预设或自定义 → 配置 API Key → 保存

通用提供商：

• 一个配置可以同步到多个应用（OpenCode、OpenClaw）
• 减少重复配置

编辑提供商

1. 选择提供商卡片
2. 点击 “Edit” 按钮
3. 修改配置（API Key、端点等）
4. 保存

回填机制：

• 编辑活动提供商时，会从实时文件回填配置
• 确保配置与实际使用一致

排序和复制

排序：

• 拖拽提供商卡片重新排序
• 常用提供商放在顶部

复制：

• 右键点击提供商
• 选择 “Duplicate”
• 修改副本配置

删除：

• 无法删除当前活动的提供商
• 遵循”最小侵入”设计原则，确保 CLI 工具始终可用

4.2 共享配置片段

问题：切换提供商后插件配置丢失

解决方案：共享配置片段功能

步骤：

1. 编辑提供商 → 共享配置面板
2. 点击 “从当前提供商提取”
3. 保存所有通用数据（插件配置等）
4. 创建新提供商时，勾选 “写入共享配置”（默认启用）

效果：

• 所有配置项保存在首次导入的默认提供商中
• 切换提供商时保留插件配置

4.3 MCP 服务器管理

MCP（Model Context Protocol） 是 AI 工具与外部服务交互的标准协议。

添加 MCP 服务器

1. 点击 “MCP” 按钮
2. 点击 “Add Server”
3. 选择模板或自定义配置
4. 配置服务器参数
5. 保存

应用绑定

为每个应用启用/禁用 MCP 服务器：

• Claude Code
• Codex
• Gemini CLI
• OpenCode

双向同步：

• 在 CC Switch 中修改 → 同步到实时配置文件
• 在配置文件中修改 → 回填到 CC Switch

Deep Link 导入

支持通过 URL 导入 MCP 服务器配置：

ccswitch://mcp/import?url=<配置 URL>

4.4 Prompts 管理

Prompts 是预定义的指令模板，用于指导 AI 行为。

创建 Prompts

1. 点击 “Prompts” 按钮
2. 点击 “Add Prompt”
3. 使用 Markdown 编辑器编写
4. 保存

跨应用同步

激活 Prompt 后，自动同步到对应文件：

• CLAUDE.md – Claude Code
• AGENTS.md – OpenClaw
• GEMINI.md – Gemini CLI

回填保护：

• 编辑活动 Prompt 时，从实时文件回填
• 防止配置丢失

4.5 Skills 管理

Skills 是 AI 工具的可复用能力模块。

安装 Skills

方法 1：从 GitHub 仓库

1. 点击 “Skills” 按钮
2. 浏览或搜索 GitHub 仓库
3. 一键安装到所有应用

方法 2：从 ZIP 文件

1. 点击 “Add Skill”
2. 选择 ZIP 文件
3. 安装

自定义仓库管理

添加自定义 Skills 仓库：

1. 设置 → Skills → 自定义仓库
2. 添加仓库 URL
3. 在 Skills 面板中可见

安装方式

符号链接（默认）：

• 创建从应用目录到规范副本的符号链接
• 单一事实来源，易于更新

文件复制：

• 为每个应用创建独立副本
• 当不支持符号链接时使用

自动备份

卸载 Skill 前自动备份：

• 备份位置：~/.cc-switch/skill-backups/
• 保留最近 20 个备份
• 可随时恢复

4.6 会话历史管理

Sessions 功能让你浏览、搜索和恢复所有应用的对话历史。

浏览会话

1. 点击 “Sessions” 按钮
2. 选择应用（Claude Code、Codex 等）
3. 浏览会话列表

搜索会话

• 按关键词搜索
• 按日期过滤
• 按模型过滤

恢复会话

1. 选择会话
2. 点击 “Restore”
3. 会话内容恢复到当前对话

4.7 使用统计

Usage Dashboard 追踪支出、请求和 Token 使用情况。

功能

• 支出追踪 – 查看每个提供商的花费
• 请求统计 – 请求次数和趋势
• Token 使用 – 输入/输出 Token 统计
• 趋势图表 – 可视化使用趋势
• 详细日志 – 每个请求的详细记录
• 自定义定价 – 配置每个模型的价格

配置自定义定价

1. 设置 → 使用统计 → 定价配置
2. 添加模型价格：
   • 输入价格（每百万 Token）
   • 输出价格（每百万 Token）
3. 保存

4.8 工作区编辑器（OpenClaw）

Workspace Editor 用于编辑 OpenClaw 代理文件。

支持的文件

• AGENTS.md – 代理工作区定义
• SOUL.md – 代理人格定义
• USER.md – 用户信息
• TOOLS.md – 工具配置
• HEARTBEAT.md – 心跳任务
• 其他 Markdown 文件

功能

• Markdown 编辑器
• 实时预览
• 语法高亮
• 自动保存

---

五、代理与高可用

5.1 本地代理服务

Proxy Service 提供本地代理，支持格式转换和热切换。

启动代理

1. 点击 “Proxy” 按钮
2. 配置代理设置：
   • 监听端口（默认：8080）
   • 日志级别
3. 点击 “Start”

功能

• 格式转换 – 不同提供商间的 API 格式转换
• 热切换 – 运行时切换提供商，无需重启
• 请求整流 – 修正不兼容的请求格式

配置示例

{
  "proxy": {
    "port": 8080,
    "logLevel": "info",
    "timeout": 30000
  }
}

5.2 应用接管

App Takeover 允许独立代理特定应用或提供商。

配置

1. 点击 “Proxy” → “App Takeover”
2. 选择要接管的应用：
   • Claude Code
   • Codex
   • Gemini CLI
3. 配置代理设置
4. 启用

状态指示

• 🟢 运行中 – 代理正常工作
• 🟡 警告 – 部分功能受限
• 🔴 错误 – 代理失败

5.3 故障转移（Failover）

Failover 提供自动故障转移和熔断器功能。

故障转移队列

1. 创建提供商队列（主→备 1→备 2）
2. 主提供商失败时自动切换到备用
3. 支持健康检查

熔断器

• 连续失败后触发熔断
• 暂停请求一段时间
• 自动恢复尝试

健康监控

• 定期检查提供商健康状态
• 延迟测试
• 成功率统计

5.4 模型测试

Model Test 用于测试模型可用性和延迟。

功能

• 健康检查 – 测试 API 连通性
• 延迟测试 – 测量响应时间
• 功能测试 – 验证模型能力

使用方法

1. 选择提供商
2. 选择模型
3. 点击 “Test”
4. 查看结果

---

六、云同步

6.1 支持的云服务

服务	说明
Dropbox	同步到 Dropbox 文件夹
OneDrive	同步到 OneDrive 文件夹
iCloud	macOS/iOS 设备同步
WebDAV	自定义 WebDAV 服务器（如 NAS）

6.2 配置云同步

1. 设置 → 云同步
2. 选择云服务类型
3. 授权或配置服务器
4. 选择同步目录
5. 启用同步

6.3 自定义配置目录

将配置目录移动到云同步文件夹：

1. 设置 → 目录
2. 修改配置目录路径
3. 重启应用

示例路径：

• Dropbox: ~/Dropbox/cc-switch/
• OneDrive: ~/OneDrive/cc-switch/
• iCloud: ~/Library/Mobile Documents/com~apple~CloudDocs/cc-switch/

6.4 WebDAV 配置

服务器地址：https://your-nas.com/webdav
用户名：your-username
密码：your-password
路径：/cc-switch/

---

七、Deep Link 协议

Deep Link 允许通过 URL 导入配置。

7.1 协议格式

ccswitch://<action>?<params>

7.2 支持的 Action

导入提供商

ccswitch://provider/import?url=<配置 URL>

导入 MCP 服务器

ccswitch://mcp/import?url=<配置 URL>

导入 Prompts

ccswitch://prompts/import?url=<配置 URL>

导入 Skills

ccswitch://skills/import?url=<仓库 URL>

7.3 生成 Deep Link

1. 配置好提供商/MCP/Prompts/Skills
2. 点击 “Share” 按钮
3. 生成 Deep Link URL
4. 分享给他人

7.4 使用示例

分享提供商配置：

ccswitch://provider/import?name=MyProvider&endpoint=https://api.example.com&model=claude-sonnet

分享 MCP 服务器：

ccswitch://mcp/import?url=https://example.com/mcp-config.json

---

八、数据存储

8.1 存储位置

数据类型	位置	说明
数据库	~/.cc-switch/cc-switch.db	SQLite – 提供商、MCP、Prompts、Skills
本地设置	~/.cc-switch/settings.json	设备级 UI 偏好
备份	~/.cc-switch/backups/	自动轮换，保留最近 10 个
Skills	~/.cc-switch/skills/	默认符号链接到对应应用
Skill 备份	~/.cc-switch/skill-backups/	卸载前自动备份，保留最近 20 个

8.2 备份机制

自动备份：

• 配置更改时自动备份
• 保留最近 10 个备份
• 手动备份：设置 → 备份 → 立即备份

恢复备份：

1. 设置 → 备份
2. 选择备份文件
3. 点击 “恢复”

8.3 导出数据

导出所有配置：

1. 设置 → 导出
2. 选择导出格式（JSON）
3. 保存到文件

导入配置：

1. 设置 → 导入
2. 选择配置文件
3. 确认导入

---

九、常见问题

9.1 配置相关

Q：切换提供商后插件配置消失了？

A：使用”共享配置片段”功能：

1. 编辑提供商 → 共享配置面板
2. 点击”从当前提供商提取”
3. 创建新提供商时勾选”写入共享配置”

Q：为什么无法删除当前活动的提供商？

A：遵循”最小侵入”设计原则，确保 CLI 工具始终可用。系统总是保留一个活动配置。

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

A：

1. 从预设列表添加”Official Login”提供商
2. 切换到该提供商
3. 重启 CLI 工具
4. 按照 CLI 工具的登录/OAuth 流程操作

Q：macOS 显示”身份不明开发者”警告？

A：

1. 关闭警告对话框
2. 系统设置 → 隐私与安全 → 仍要打开
3. 之后即可正常打开

9.2 生效相关

Q：切换提供商后需要重启终端吗？

A：

• Claude Code：不需要，支持热切换
• 其他工具：需要重启终端或 CLI 工具

Q：如何确认配置已生效？

A：

1. 检查系统托盘图标状态
2. 运行 CLI 工具测试命令
3. 查看使用统计中的请求记录

9.3 冲突相关

Q：环境变量冲突如何解决？

A：

1. 设置 → 环境变量
2. 检查冲突检测
3. 移除或重命名冲突变量

Q：多个 CLI 工具同时使用会冲突吗？

A：不会。每个工具有独立的配置文件，CC Switch 分别管理。

9.4 性能相关

Q：代理模式会影响性能吗？

A：

• 轻微延迟（通常<10ms）
• 故障转移可能增加延迟
• 建议本地运行代理服务

Q：云同步会拖慢应用吗？

A：

• 同步在后台进行
• 仅在配置更改时同步
• 大文件同步可能耗时

---

十、最佳实践

10.1 提供商管理

组织提供商：

• 按用途分组（开发、测试、生产）
• 常用提供商置顶
• 使用描述性名称

备份配置：

• 定期导出配置
• 云同步开启
• 重大更改前手动备份

10.2 MCP 配置

共享服务器：

• 团队共享的 MCP 服务器使用 Deep Link 分发
• 统一配置版本
• 定期更新服务器

本地服务器：

• 开发环境使用本地 MCP
• 生产环境使用远程 MCP
• 使用不同提供商区分

10.3 Skills 管理

版本控制：

• 使用固定版本的 Skills 仓库
• 定期更新 Skills
• 备份自定义 Skills

团队共享：

• 创建团队 Skills 仓库
• 使用 Deep Link 分发
• 统一 Skills 版本

10.4 安全建议

API Key 保护：

• 不在公开场合分享配置
• 使用环境变量存储敏感信息
• 定期轮换 API Key

访问控制：

• 限制 MCP 服务器权限
• 使用只读 API Key（如可能）
• 监控使用统计异常

---

十一、技术架构

11.1 架构概览

┌─────────────────────────────────────────────────────────────┐
│ Frontend (React + TS)                                        │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐       │
│ │ Components  │ │ Hooks        │ │ TanStack Query   │       │
│ │ (UI)        │──│ (Bus. Logic) │──│ (Cache/Sync)    │       │
│ └─────────────┘ └──────────────┘ └──────────────────┘       │
└────────────────────────┬────────────────────────────────────┘
                         │ Tauri IPC
┌────────────────────────▼────────────────────────────────────┐
│ Backend (Tauri + Rust)                                       │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────────┐       │
│ │ Commands    │ │ Services     │ │ Models/Config    │       │
│ │ (API Layer) │──│ (Bus. Layer) │──│ (Data)         │       │
│ └─────────────┘ └──────────────┘ └──────────────────┘       │
└─────────────────────────────────────────────────────────────┘

11.2 核心设计模式

模式	说明
SSOT	单一事实来源 – 所有数据存储在 SQLite 数据库
双层存储	SQLite 存储可同步数据，JSON 存储设备级设置
双向同步	切换时写入实时文件，编辑时从实时文件回填
原子写入	临时文件 + 重命名模式，防止配置损坏
并发安全	互斥锁保护的数据库连接，避免竞态条件
分层架构	清晰分离（Commands → Services → DAO → Database）

11.3 技术栈

前端：

• React 18
• TypeScript
• Vite
• TailwindCSS 3.4
• TanStack Query v5
• react-i18next
• react-hook-form
• zod
• shadcn/ui
• @dnd-kit

后端：

• Tauri 2.8
• Rust
• serde
• tokio
• thiserror
• tauri-plugin-updater/process/dialog/store/log

测试：

• vitest
• MSW (Mock Service Worker)
• @testing-library/react

---

十二、开发与贡献

12.1 开发环境要求

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

12.2 快速开始

# 克隆仓库
git clone https://github.com/farion1231/cc-switch.git
cd cc-switch

# 安装依赖
pnpm install

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

# 类型检查
pnpm typecheck

# 格式化代码
pnpm format

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

# 构建应用
pnpm build

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

12.3 后端开发

cd src-tauri

# 格式化 Rust 代码
cargo fmt

# 运行 clippy 检查
cargo clippy

# 运行后端测试
cargo test

# 运行特定测试
cargo test test_name

# 使用 test-hooks 功能运行测试
cargo test --features test-hooks

12.4 前端测试

# 运行所有测试
pnpm test:unit

# 监视模式（自动重运行）
pnpm test:unit:watch

# 带覆盖率报告
pnpm test:unit --coverage

12.5 提交 PR

提交 PR 前请确保：

• ✅ 通过类型检查：pnpm typecheck
• ✅ 通过格式化检查：pnpm format:check
• ✅ 通过单元测试：pnpm test:unit

新功能：

• 先开 Issue 讨论
• 确认适合项目后再提交 PR

---

十三、赞助商与资源

13.1 API 中继服务

CC Switch 与多个 API 中继服务提供商合作，为用户提供优惠：

服务商	优惠	注册链接
PackyCode	首次充值 9 折	注册
SiliconFlow	实名送¥20	注册
AIGoCode	首次充值额外 10% 赠送	注册
AICodeMirror	首次充值 8 折	注册
Cubence	每次充值 9 折	注册
DMXAPI	GPT/Claude/Gemini 32 折	注册
Compshare	送 5 元试用金	注册
Right Code	充值送 25% 点数	注册
AICoding.sh	首次充值 9 折	注册
Crazyrouter	注册送$2 + 充值 30% 赠送	注册

13.2 学习资源

• 官方文档：User Manual
• 更新日志：CHANGELOG
• 问题反馈：GitHub Issues
• 社区讨论：GitHub Discussions

---

十四、总结

CC Switch 核心价值：

✅ 统一管理 – 一个应用管理五个 AI 编码工具
✅ 无需手动编辑 – 可视化界面，一键切换
✅ 50+ 预设 – 内置主流提供商，开箱即用
✅ MCP/Prompts/Skills – 统一扩展管理
✅ 代理高可用 – 故障转移、熔断器、健康监控
✅ 云同步 – 跨设备同步配置
✅ 跨平台 – Windows、macOS、Linux 原生支持
✅ 开源免费 – MIT 许可证，社区驱动

适用人群：

• 同时使用多个 AI 编码工具的开发者
• 需要频繁切换 API 提供商的团队
• 想要统一管理 MCP 和 Skills 的用户
• 需要故障转移和高可用的生产环境

下一步行动：

1. 下载安装 CC Switch
2. 导入现有配置或添加第一个提供商
3. 配置 MCP 服务器和 Skills
4. 开启云同步
5. 探索高级功能（代理、故障转移、使用统计）

---

参考资料：

• CC Switch GitHub
• 用户手册
• 更新日志
• 问题反馈

---

本文基于 CC Switch v3.12.3 编写，功能可能随版本更新而变化。请参考官方文档获取最新信息。