CC Switch：解决 AI 编程工具配置

一、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）

bash 复制代码

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

bash 复制代码

# Arch Linux
paru -S cc-switch-bin

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

CLI 版本

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

快速安装（macOS / Linux）

bash 复制代码

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

从源码构建

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 首次使用流程

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

5.2 CLI 常用命令

bash 复制代码

# 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 字段配置映射：

bash 复制代码

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

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

几乎不会。

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

Q4：CC Switch 本身会收费吗？

不会。

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