CC Switch 超级详细使用教程

版本：v3.13+　｜　平台：Windows / macOS / Linux　｜　技术：Tauri 2 + Rust
项目地址：https://github.com/farion1231/cc-switch
最后更新：2026-04

目录

1. 什么是 CC Switch
2. 下载与安装
3. 首次启动与界面说明
4. 供应商管理（Provider）
5. 本地代理与自动故障转移
6. MCP 服务器管理
7. Prompts 系统提示词管理
8. Skills 技能扩展管理
9. 用量与费用统计
10. 会话管理器（Session Manager）
11. 备份与恢复
12. 云端同步
13. Claude Rectifier（思考签名修复器）
14. CLI 命令行模式
15. 各应用专属配置
16. 数据存储位置
17. 常见问题（FAQ）
18. 实用技巧汇总

1. 什么是 CC Switch

CC Switch 是由 Jason Young（farion1231） 开发的一款基于 Tauri 2 + Rust 构建的跨平台原生桌面应用，定位为 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 五大 AI 编程 CLI 工具的全方位一体化管理平台。

解决的痛点

• 不同 CLI 工具配置格式各异（JSON、TOML、.env），切换时需手动编辑多个文件
• 使用多个 API 供应商时，Key 和 BaseURL 分散在各处难以维护
• MCP 服务器、Skills 扩展缺乏统一管理入口
• 没有统一的用量监控和费用追踪

核心功能

技术架构

2. 下载与安装

下载地址：https://github.com/farion1231/cc-switch/releases/latest

Windows

1. 从 Release 页面下载 CC-Switch-vX.X.X-Windows.msi（推荐，支持自动更新）或下载 CC-Switch-vX.X.X-Windows-Portable.zip（便携版，无需安装）
2. 双击 .msi 文件，按向导完成安装
3. 在开始菜单搜索"CC Switch"启动

⚠️ 遇到 Windows SmartScreen 拦截：点击 "更多信息" → "仍要运行"

macOS

方式一：Homebrew（推荐）

# 添加 tap
brew tap farion1231/ccswitch

# 安装
brew install --cask cc-switch

# 更新
brew upgrade --cask cc-switch

方式二：直接下载

下载 CC-Switch-vX.X.X-macOS.zip，解压后将 CC Switch.app 拖入「应用程序」文件夹。
首次启动右键点击 → 打开，或前往「系统设置 → 隐私与安全性 → 仍要打开」。

Linux

系统要求

3. 首次启动与界面说明

安装完成后启动 CC Switch，首次启动会自动扫描系统中已安装的 CLI 工具并尝试导入现有配置。

界面布局

┌─────────────────────────────────────────────────────────────┐
│  ● CC Switch   [Claude] [Codex] [Gemini] [OpenCode] [OpenClaw]  [⚙ 设置]  │
├────────────────────────┬────────────────────────────────────┤
│  左侧：功能导航         │  右侧：内容区域                      │
│                        │                                    │
│  • Providers (供应商)  │  供应商卡片列表                      │
│  • MCP                 │  当前启用：[供应商名]                 │
│  • Prompts             │  + 添加供应商                        │
│  • Skills              │                                    │
│  • Sessions (会话)     │                                    │
│  • Usage (用量)        │                                    │
└────────────────────────┴────────────────────────────────────┘

首次配置步骤

第 1 步：进入设置 → 开启插件接管

点击右上角⚙齿轮图标进入设置，在 "通用" 选项卡中，开启 "应用到 Claude Code 插件" 的开关。建议同时开启 "开机自启"。

第 2 步：选择要管理的应用

主界面顶部为应用切换栏，点击对应图标切换管理的 CLI 工具（Claude / Codex / Gemini / OpenCode / OpenClaw）。

第 3 步：添加第一个 API 供应商

点击右上角 "+" 按钮，选择内置预设或手动填写供应商信息。

第 4 步：启用供应商

在供应商列表中点击目标卡片，点击 "启用" 按钮，等待显示 "使用中" 即完成。

第 5 步：重启终端让配置生效

打开新终端，运行 claude / codex 等命令即可使用新配置。

⚠️ Claude Code 支持热切换（无需重启终端），其他工具切换后需重启终端。

4. 供应商管理（Provider）

供应商（Provider）是 CC Switch 的核心概念，每一条供应商配置包含 API Key、请求地址、模型名称等信息。

添加供应商

点击主界面右上角 "+"，填写以下信息：

⚠️ API 请求地址注意：不要在末尾多加 /，也不要重复加 /v1，工具会自动处理路径拼接。

统一供应商（Universal Provider）v3.9.0+

统一供应商只需配置一次，即可同步到多个 CLI 工具，省去重复配置的麻烦。

配置步骤：

1. 在添加供应商界面，点击顶部的 "统一供应商" 标签
2. 选择预设类型：NewAPI（适合大多数中转站）或 自定义网关
3. 填入名称、API 地址（如 https://api.gemai.cc）、API Key
4. 勾选希望同步的 CLI 工具：☑ Claude Code　☑ Codex　☑ Gemini CLI　☑ OpenCode　☑ OpenClaw
5. 为每个工具指定默认模型（如为 Gemini 映射 gemini-2.5-pro-preview）
6. 点击 "添加" 完成，配置自动分发到所有勾选的工具

切换供应商

其他供应商操作

5. 本地代理与自动故障转移

CC Switch 内置了强大的本地代理层，支持格式转换、自动故障转移、熔断器机制和供应商健康监控。

核心功能

配置（设置 → 代理）

💡 开启代理后，CC Switch 会自动更新 CLI 工具的 ANTHROPIC_BASE_URL / OPENAI_BASE_URL 等环境变量，指向本地代理地址。

6. MCP 服务器管理

MCP（Model Context Protocol）是 AI CLI 工具的扩展协议，允许 AI 调用外部工具（文件系统、数据库、浏览器等）。CC Switch 提供统一管理面板，支持跨应用配置同步。

支持的传输类型

添加 MCP 服务器（GUI）

1. 点击左侧导航 "MCP" 进入管理页面
2. 点击 "+ 添加服务器"，弹出编辑窗口
3. 填写服务器配置（以 stdio 类型为例）：

4. 勾选同步到哪些应用（Claude / Codex / Gemini CLI / OpenCode / OpenClaw）
5. 点击 "同步" 按钮，写入各 CLI 工具配置文件

Deep Link 一键导入 MCP

# 格式示例（在浏览器或终端中打开）
ccswitch://mcp/import?config=<base64编码的配置>

很多 MCP 工具的文档页面会提供这类链接，点击即可自动导入。

MCP 双向同步机制

• 写入方向：切换供应商时，CC Switch 将 MCP 配置写入 CLI 工具的 live 配置文件
• 回填方向：编辑当前供应商时，自动从 live 配置文件回读最新值
• 原子写入：使用临时文件 + 重命名方式，防止配置写入损坏

7. Prompts 系统提示词管理

CC Switch 内置 Markdown 编辑器，统一管理多款 CLI 工具的系统提示词，支持跨应用同步。

对应文件

使用步骤

1. 进入左侧 "Prompts" 面板
2. 点击 "+ 新建提示词"，在 Markdown 编辑器中编写内容
3. 保存后，选择该提示词，点击 "激活"
4. CC Switch 自动将内容写入对应工具的提示词文件
5. 如需停用，点击 "停用" 即可

💡 回填保护：手动修改了 CLAUDE.md 文件后，CC Switch 在下次编辑时会从文件回读最新内容，避免覆盖手动修改。

8. Skills 技能扩展管理

Skills 是针对 Claude Code / Codex 等工具的提示词增强扩展包，CC Switch 采用 SSOT（Single Source of Truth）架构，通过软链接同步到各应用目录。

安装方式

同步方式

仓库管理

支持自定义 GitHub 技能仓库，格式为 owner/repo 或 owner/repo@branch：

farion1231/cc-skills          # 使用默认分支
myorg/my-skills@main          # 指定分支
https://github.com/xxx/yyy   # 完整 GitHub URL

数据存储

9. 用量与费用统计

进入左侧导航 "Usage（用量）" 页面，查看跨供应商的 API 使用情况：

自定义模型定价

在 设置 → 定价配置 中，为每个模型设置每百万 Token 的费用，CC Switch 据此精确计算实际花费。

10. 会话管理器（Session Manager）

进入左侧 "Sessions（会话）" 页面，浏览、搜索和恢复历史对话：

11. 备份与恢复

进入 设置 → 备份管理。

备份类型

备份文件位置

~/.cc-switch/backups/        # 配置备份目录
~/.cc-switch/skill-backups/  # 技能备份目录

恢复操作

1. 进入 设置 → 备份管理
2. 在备份列表中找到目标版本
3. 点击 "恢复" 按钮，确认后 CC Switch 自动替换当前配置
4. 重启应用使恢复生效

✅ 原子写入保证：即使在恢复过程中意外中断，也不会导致配置文件损坏。

12. 云端同步

方式一：自定义配置目录

在 设置 → 同步 中，将数据库目录指向云盘同步文件夹：

方式二：WebDAV 同步

进入 设置 → WebDAV 同步，填写：

⚠️ 内置大文件保护机制：上传前会检查文件大小，防止误传超大文件。

13. Claude Rectifier（思考签名修复器）

使用某些第三方 API 网关时，Claude 的 Extended Thinking（思考过程） 功能可能因签名格式不兼容而报错。Rectifier 是内置的代理层拦截器，可自动修复此问题。

14. CLI 命令行模式

除图形界面外，CC Switch 还提供完整的 CLI 版本，适合服务器环境、脚本自动化、SSH 远程操作等场景。

CLI 版安装

macOS：

sudo mv cc-switch-cli /usr/local/bin/cc-switch
sudo chmod +x /usr/local/bin/cc-switch

Linux：

tar -xzf cc-switch-cli-linux-x64-musl.tar.gz
sudo mv cc-switch /usr/local/bin/

Windows（PowerShell）：

Move-Item cc-switch.exe C:\Windows\System32\

供应商管理命令

cc-switch provider list              # 列出所有供应商
cc-switch provider current           # 显示当前激活的供应商
cc-switch provider switch <id>       # 切换到指定供应商
cc-switch provider add               # 交互式添加新供应商
cc-switch provider edit <id>         # 编辑指定供应商
cc-switch provider duplicate <id>    # 复制供应商
cc-switch provider delete <id>       # 删除供应商
cc-switch provider speedtest <id>    # 测试 API 延迟

# 使用 --app 参数指定目标应用
cc-switch --app claude provider list    # 管理 Claude Code 供应商
cc-switch --app codex provider list     # 管理 Codex 供应商
cc-switch --app gemini provider list    # 管理 Gemini CLI 供应商

MCP 管理命令

cc-switch mcp list                        # 列出所有 MCP 服务器
cc-switch mcp add                         # 交互式添加 MCP 服务器
cc-switch mcp edit <id>                   # 编辑 MCP 服务器
cc-switch mcp delete <id>                 # 删除 MCP 服务器
cc-switch mcp enable <id> --app claude    # 为 Claude 启用指定 MCP
cc-switch mcp disable <id> --app claude   # 为 Claude 禁用指定 MCP
cc-switch mcp validate <command>          # 验证命令是否在 PATH 中可用
cc-switch mcp sync                        # 同步 MCP 配置到 live 配置文件
cc-switch mcp import --app claude         # 从 Claude live 配置导入 MCP

Prompts 管理命令

cc-switch prompts list               # 列出所有提示词预设
cc-switch prompts current            # 显示当前激活的提示词
cc-switch prompts activate <id>      # 激活提示词
cc-switch prompts deactivate         # 停用当前提示词
cc-switch prompts create             # 创建新提示词预设
cc-switch prompts edit <id>          # 编辑提示词
cc-switch prompts show <id>          # 查看完整提示词内容
cc-switch prompts delete <id>        # 删除提示词

Skills 管理命令

cc-switch skills list                # 列出已安装的技能
cc-switch skills search <query>      # 搜索可用技能
cc-switch skills install <name>      # 安装技能
cc-switch skills uninstall <name>    # 卸载技能
cc-switch skills enable <name>       # 为当前应用启用技能
cc-switch skills disable <name>      # 为当前应用禁用技能
cc-switch skills info <name>         # 查看技能详情
cc-switch skills sync                # 同步已启用技能到各应用目录
cc-switch skills sync-method [m]     # 查看/设置同步方式（auto|symlink|copy）
cc-switch skills scan-unmanaged      # 扫描未被 SSOT 管理的技能
cc-switch skills import-from-apps    # 将未管理技能导入 SSOT 仓库

# 仓库管理
cc-switch skills repos list          # 查看仓库列表
cc-switch skills repos add <repo>    # 添加仓库
cc-switch skills repos remove <repo> # 移除仓库

配置管理命令

# 查看与验证
cc-switch config show                          # 显示当前配置
cc-switch config path                          # 显示配置文件路径
cc-switch config validate                      # 验证配置文件

# 备份
cc-switch config backup                        # 自动命名备份
cc-switch config backup --name my-backup       # 自定义名称备份

# 恢复
cc-switch config restore                       # 交互式选择版本恢复
cc-switch config restore --backup <id>         # 按 ID 恢复
cc-switch config restore --file <path>         # 从外部文件恢复

# 导入/导出
cc-switch config export <path>                 # 导出配置到文件
cc-switch config import <path>                 # 从文件导入配置

# 通用配置片段（跨供应商共享的配置）
cc-switch --app claude config common show
cc-switch --app claude config common set --json '{"env":{"DISABLE_TELEMETRY":1}}' --apply
cc-switch --app claude config common clear --apply

# 重置
cc-switch config reset                         # 重置为默认配置

15. 各应用专属配置

Claude Code

• 点击顶部标签栏 Claude 图标进入管理界面
• 添加供应商时 API 格式选择 "Anthropic Messages 原生格式" 或 "OpenAI Chat Completions 兼容格式"
• Claude Code 支持热切换，切换供应商后无需重启终端，立即生效
• 设置中勾选 "跳过 Claude Code 初次安装确认" 可跳过每次初始化的确认弹窗
• 支持官方账号登录预设，可在官方 API Key 模式与官方账号登录模式之间随时切换

OpenAI Codex

• 点击顶部标签栏 Codex 图标
• 填写与通用配置相同的 Base URL 和 API Key
• 切换后需重启终端才能生效
• 支持多个 Plus / Team 官方账号间切换（包月用户专属功能）
• 包月用户的 API 请求地址需替换为专属地址，并从包月控制台获取 API Key

Gemini CLI

• 点击顶部标签栏 Gemini 图标
• 认证方式选择 "API Key（Bearer Token）模式"
• 填写 API Key 和 Base URL 后点击保存
• 切换后需重启终端才能生效
• 使用统一供应商时，可为 Gemini 单独映射模型名称（如 gemini-2.5-pro-preview）

OpenCode

• 点击顶部标签栏 OpenCode 图标
• 添加并保存供应商后，点击卡片即可将其设为 Active 状态
• 支持通用供应商（Universal Provider）配置共享
• 切换后需重启终端才能生效

OpenClaw v3.11.0+

• 点击顶部标签栏 OpenClaw 图标
• 提供 Env、Tools 和 AgentsDefaults 三个编辑面板，可进一步微调 OpenClaw 的工作行为
• 工作区编辑器：可直接编辑 AGENTS.md、SOUL.md 等 Agent 文件，支持 Markdown 预览
• 切换后需重启终端才能生效

16. 数据存储位置

💡 卸载 CC Switch 不会删除上述数据文件，也不会影响各 CLI 工具的正常使用。

17. 常见问题（FAQ）

Q：切换供应商后，终端里的 CLI 工具没有使用新配置？

除 Claude Code 外，其他工具切换后需要重启终端会话。关闭当前终端窗口，打开新窗口后重新运行命令即可。

Q：Windows 安装时被 SmartScreen 拦截怎么办？

点击 "更多信息"，然后点击 "仍要运行"。CC Switch 是开源软件，代码可在 GitHub 查看，无安全风险。

Q：API 请求地址应该填到 /v1 还是不带 /v1？

根据供应商文档为准。若文档说 Base URL 是 https://api.xxx.com/v1，就填 https://api.xxx.com/v1。不要随意增减，末尾不要加 /。

Q：能否同时管理多个 Claude Code 账号？

可以。为每个账号创建一个供应商（选择 "官方登录" 预设），通过 CC Switch 切换时会自动切换到对应账号的认证令牌。

Q：MCP 配置同步后，原有手动配置的 MCP 会不会被覆盖？

CC Switch 会先从 live 配置文件回填（双向同步机制），再写入新配置，手动添加的 MCP 项目会被保留。建议统一通过 CC Switch 管理，避免冲突。

Q：数据库文件损坏了怎么恢复？

进入 设置 → 备份管理，选择最近的自动备份版本，点击 "恢复" 即可。CC Switch 的原子写入机制大幅降低了损坏概率。

Q：Linux 使用 AppImage 时如何设置开机自启？

在 CC Switch 设置中开启 "开机自启" 选项即可，CC Switch 会自动在 ~/.config/autostart/ 创建 .desktop 文件。

18. 实用技巧汇总

📖 更多资源

• 官方 GitHub：https://github.com/farion1231/cc-switch
• 官方文档（中文）：https://github.com/farion1231/cc-switch/tree/main/docs/user-manual/zh
• 问题反馈：https://github.com/farion1231/cc-switch/issues