一、CC Switch 是什么？

CC Switch 是一款跨平台桌面应用（同时也有 CLI 版本），用于统一管理多个 AI 编程 CLI 工具的配置。它支持以下五种 AI 编程助手：

• Claude Code（Anthropic）
• Codex（OpenAI）
• Gemini CLI（Google）
• OpenCode
• OpenClaw

每个 AI CLI 工具都有自己独立的配置格式（JSON、TOML、.env），手动切换 API Provider 意味着频繁编辑配置文件。CC Switch 将这些操作统一到一个可视化界面中，无需手动编辑配置文件。

核心定位

CC Switch 不是一个简单的"切换器"，而是一个本地 AI CLI 运维控制台——涵盖 Provider 管理、代理转发、MCP/Prompts/Skills 扩展同步、会话浏览、用量追踪和云端同步。

二、CC Switch 解决什么问题？

痛点	CC Switch 的解决方案
每个 CLI 工具配置格式不同（JSON/TOML/.env）	统一 UI 管理，一键切换
切换 Provider 需要手动编辑文件	50+ 内置 Provider 预设，点击即用
MCP Server 配置分散在各个目录	统一面板管理，跨应用同步
无法追踪 Token 用量和费用	内置用量仪表盘和费用追踪
多设备配置不同步	支持 WebDAV / Dropbox / OneDrive / iCloud 云同步
配置文件损坏风险	SQLite 数据库 + 原子写入 + 自动备份

三、核心功能

3.1 Provider

Provider 是 CC Switch 的核心概念，代表一个 API 接入点配置（包含 API Key、Endpoint、Model 等信息）。

工作原理：

用户选择 Provider → CC Switch 写入对应 CLI 的配置文件 → 重启终端生效

各 CLI 工具的配置文件位置：

• Claude：~/.claude/settings.json
• Codex：~/.codex/config.toml
• Gemini：~/.gemini/.env
• OpenCode：~/.config/opencode/opencode.json
• OpenClaw：~/.openclaw/openclaw.json

3.2 MCP Server

MCP（Model Context Protocol）是 AI 编程工具的扩展协议。CC Switch 提供统一面板管理跨应用的 MCP Server。

功能特性：

• 支持三种传输类型：stdio / http / sse
• 跨应用双向同步
• Deep Link 导入
• 模板快速添加
• 按应用启用/禁用

3.3 Prompts

管理各 CLI 工具的系统提示词预设。

对应文件：

• Claude → CLAUDE.md
• Codex → AGENTS.md
• Gemini → GEMINI.md
• OpenCode → AGENTS.md
• OpenClaw → AGENTS.md

功能特性：

• Markdown 编辑器
• 跨应用同步
• 回填保护（防止覆盖已有内容）
• 预设管理（创建/激活/停用）

3.4 Skills

Skills 是可复用的能力扩展包，可以从 GitHub 仓库一键安装。

功能特性：

• 从 GitHub 仓库发现和安装 Skills
• 按应用启用/禁用
• 同步到应用目录（支持 symlink 和文件复制）
• 自定义仓库管理
• 扫描和导入未管理的 Skills

3.5 代理与故障转移

CC Switch 内置本地代理服务，支持：

• 热切换（不中断请求）
• 格式转换（不同 Provider API 格式适配）
• 自动故障转移（Provider 不可用时自动切换）
• 熔断器机制
• Provider 健康监控
• 请求修正器

3.6 会话管理

• 浏览、搜索所有应用的对话历史
• 恢复历史会话
• 跨应用统一视图

3.7 用量与费用追踪

• Token 用量统计
• 费用趋势图表
• 详细请求日志
• 自定义模型定价

四、安装方式

桌面版（GUI）

macOS（推荐 Homebrew）

brew tap farion1231/ccswitch
brew install --cask cc-switch

# 更新
brew upgrade --cask cc-switch

Windows

从 Releases 下载：

• CC-Switch-v{version}-Windows.msi（安装版）
• CC-Switch-v{version}-Windows-Portable.zip（便携版）

Linux

# Arch Linux
paru -S cc-switch-bin

# Debian/Ubuntu: 下载 .deb
# Fedora/RHEL: 下载 .rpm
# 通用: 下载 .AppImage

CLI 版本

如果更喜欢命令行操作，可以安装 CLI 版本：

快速安装（macOS / Linux）

curl -fsSL https://github.com/SaladDay/cc-switch-cli/releases/latest/download/install.sh | bash

从源码构建

git clone https://github.com/saladday/cc-switch-cli.git
cd cc-switch-cli/src-tauri
cargo build --release
sudo cp target/release/cc-switch /usr/local/bin/

五、使用指南

5.1 首次使用流程

1. 导入现有配置 — 首次启动时，将当前 CLI 工具的配置导入为默认 Provider
2. 添加 Provider — 从预设列表选择或创建自定义端点
3. 同步扩展 — 将 MCP、Prompts、Skills 统一管理
4. 按需切换 — 通过主界面或系统托盘切换 Provider

5.2 CLI 常用命令

# Provider 管理
cc-switch provider list              # 列出所有 Provider
cc-switch provider current           # 显示当前 Provider
cc-switch provider switch <id>       # 切换 Provider
cc-switch provider add               # 添加新 Provider
cc-switch provider speedtest <id>    # 测试 API 延迟
cc-switch provider stream-check <id> # 流式健康检查

# MCP 管理
cc-switch mcp list                   # 列出所有 MCP Server
cc-switch mcp add                    # 添加 MCP Server
cc-switch mcp sync                   # 同步到实际配置文件
cc-switch mcp import --app claude    # 从实际配置导入

# Prompts 管理
cc-switch prompts list               # 列出提示词预设
cc-switch prompts activate <id>      # 激活预设
cc-switch prompts deactivate         # 停用当前预设

# Skills 管理
cc-switch skills discover <query>    # 搜索可用 Skills
cc-switch skills install <name>      # 安装 Skill
cc-switch skills sync                # 同步到应用目录

# 配置管理
cc-switch config backup              # 创建备份
cc-switch config restore             # 恢复备份
cc-switch config webdav upload       # 上传到 WebDAV
cc-switch config webdav download     # 从 WebDAV 下载

# 代理管理
cc-switch proxy show                 # 查看代理配置
cc-switch proxy enable               # 启用代理
cc-switch proxy disable              # 禁用代理

# 环境检查
cc-switch env check                  # 检查环境冲突
cc-switch env tools                  # 检查 CLI 工具安装状态

# 指定应用
cc-switch --app codex provider list  # 管理 Codex 的 Provider
cc-switch --app gemini mcp sync      # 同步 Gemini 的 MCP

5.3 交互模式

直接运行 cc-switch 不带参数即可进入交互式 TUI 模式，通过菜单导航操作。

六、常见问题

Q1：切换后 Claude Code 没生效？

CC Switch 修改的是配置文件，已运行的 CLI 进程不会自动感知。必须重启：

# 方式一：在 Claude Code 中退出再启动
/exit
claude

# 方式二：关闭终端窗口，重新打开

如果还不行，检查：

• CC Switch 中该 Provider 状态是否为 "Active"
• API Key 是否完整复制（sk- 开头）
• 用内置 Test 按钮验证连接

Q2：模型映射什么时候需要配？

大多数正规中转服务模型名和官方一致，不需要配。

只有当中转服务的模型名和官方不同时才需要。比如：

• 官方：claude-sonnet-4-20250514
• 某中转：claude-4-sonnet

这时在 models 字段配置映射：

"models": {
  "claude-sonnet-4-20250514": "claude-4-sonnet"
}

Q3：本地代理会影响性能吗？

几乎不会。

代理只是在本地做一次转发，增加的延迟通常 < 1ms。Rust 实现的代理性能极高。

Q4：CC Switch 本身会收费吗？

不会。

CC Switch 是开源免费软件。它只是配置管理工具，不提供 API 服务。只需要自己准备 API Key（官方或第三方中转）。