CC Switch 是一款跨平台的桌面配置管理工具,核心作用是把 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等 AI 编程命令行工具的 API 服务商配置收进同一个界面,用可视化表单替代手改 settings.json、config.toml 和.env。它把自己定位成 “配置档案切换器”:每一份服务商配置就是一个档案,切换时只替换端点、Key、模型名、协议这几个关键字段,其余内容保留,同一时刻只有一份配置处于启用状态。截至 v4.0.21(2026 年 10 月 26 日发布),官方 README 列出的受管客户端已经扩展到 13 款,除了 Claude Code 和 Codex,还包括 Claude Desktop、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code、Kimi Code、Oh My Pi 和 Antigravity CLI;内置 50 多个服务商预设,覆盖官方登录、社区中转和自定义端点,支持 Windows、macOS、Linux 三端。它真正省事的地方不在 “能切换”,而在把切换之后的配套动作也接上了:MCP 服务器、提示词、Skills 统一管理,本地路由与故障转移,会话与 Token 用量查看,配置备份与云同步,以及 ccswitch:// 一键导入链接。
一、它解决的是哪几个具体麻烦
| 原来的做法 | CC Switch 的做法 | 省下的动作 |
|---|---|---|
| 手改 settings.json、config.toml、.env | 表单填写,自动写入对应文件 | 不用记字段名和缩进 |
| 换服务商要复制粘贴 Key 和地址 | 点卡片 “启用” 即切换 | 不用来回翻文档 |
| MCP、提示词、Skills 分散在各工具目录 | 一个面板统一导入、同步、回写 | 不用逐个文件夹找 |
| 多套配置容易互相覆盖 | 只替换关键字段,首次改写前自动备份 | 降低配置漂移风险 |
| 用量和花费要开多个后台查 | 会话、请求日志、Token 用量、模型价格集中看 | 不用来回切账号 |
| 临时想换节点要开主界面 | 系统托盘按应用分组直接切 | 不用重新打开窗口 |
二、13 款受管客户端
| 客户端 | 类型 | 典型配置文件 |
|---|---|---|
| Claude Code | CLI | ~/.claude/settings.json |
| Claude Desktop | 桌面应用 | 3P 配置文件(macOS 在 Claude-3p 目录) |
| Codex | CLI / 桌面版 | ~/.codex/config.toml、auth.json |
| Gemini CLI | CLI | 对应 Gemini 配置目录 |
| Grok Build | CLI | 对应配置目录 |
| OpenCode | CLI | 对应配置目录 |
| OpenClaw | CLI | 对应配置目录 |
| Hermes Agent | CLI | config.yaml |
| Pi | CLI | 对应配置目录 |
| MiniMax Code | CLI | 对应配置目录 |
| Kimi Code | CLI | ~/.kimi-code/config.toml |
| Oh My Pi | CLI | ~/.omp/agent |
| Antigravity CLI(agy) | CLI | 对应配置目录 |
不同客户端的支持深度不一样:Claude Code 和 Codex 是官方重点维护的两条主线,模型切换、路由、聚合模式、用量统计都围绕它们做得最完整;其余客户端以供应商配置管理和同步为主。
三、七个核心能力
- 服务商预设:50 多个预设,覆盖官方登录、常见中转、自定义端点,也能直接导入现有配置。
- 一键切换:主界面点 “启用”,或从系统托盘按 Claude/Codex/Gemini 分组直接切。
- 统一扩展管理:MCP 服务器、提示词文件、Skills 仓库在一个面板里配置,再同步到多个 CLI。
- 本地路由与故障转移:代理接管、健康监测、请求修正、自动切换,适合多供应商互为备份。
- 聚合模式:把多家供应商的模型放进同一个模型选择器,选哪个模型就发给哪家(目前支持 Claude Code 和 Codex,需手动开启)。
- 会话与用量:浏览对话历史、请求日志、Token 消耗和模型价格。
- 备份与同步:SQLite 存储加原子写入,支持 WebDAV 或常见云盘文件夹同步,降低配置损坏概率。
四、安装与首次配置
安装
- macOS:brew tap farion1231/ccswitch 后执行 brew install --cask cc-switch。
- Windows:下载.msi安装包或 Portable ZIP;ARM 设备选 arm64 版本。
- Linux:.deb、.rpm、.AppImage,Arch 系可用paru -S cc-switch-bin。
- 系统要求:Windows 10 及以上、macOS 12 及以上、Linux 需 x86_64 或 ARM64、glibc 2.35 以上并带 WebKitGTK 4.1。
首次配置六步
- 首次启动先导入现有环境,把当前 CLI 配置收成默认服务商,不用从零重建。
- 选左侧的 Claude Code 或 Codex 标签,点右上角 “+” 添加服务商。
- 从预设里选一个,或选 “自定义” 填 Base URL、Key、模型名。
- 需要统一术语和扩展的,到 MCP、Prompts、Skills 面板导入并选择写入哪些应用。
- 保存后点卡片 “启用”,确认对应的 live 配置文件已被改写。
- 按客户端要求重开会话或重启应用,再跑一次claude或codex验证连通。
五、切换之后要不要重启
| 客户端 | 是否需要重启 | 说明 |
|---|---|---|
| Claude Code | 通常不用 | 支持热切换,但已在运行的旧会话可能仍走旧节点,保险做法是关掉重开 |
| Codex CLI | 需要 | 重开终端后再运行 |
| Codex 桌面版 | 需要完全退出 | 只关窗口不算,macOS 用⌘Q 退出后重开 |
| Claude Desktop | 需要完全退出 | 使用模型映射时,还要保持 CC Switch 运行 |
| 聚合模式(Codex) | 需要彻底重启 | 进入、退出聚合或改模型列表后都要重启 |
| 其他 CLI | 一般需要 | 以各工具实际行为为准 |
判断标准很简单:先看~/.claude/settings.json或~/.codex/config.toml有没有变成新配置,文件变了但会话没变,就是进程没重读,重开即可。
六、多账号与聚合模式
v4.0.21 把 “多个 Claude 官方订阅账号” 做进了授权中心:
- 登录走 Claude Code 自带的官方流程,令牌只留在本机 Claude Code 的存储位置,不上传、不写进 CC Switch 数据库。
- 每个账号一个独立配置目录,用CLAUDE_CONFIG_DIR区分。
- 切换官方卡即切换账号,已在运行的 Claude Code 会立即跟着换,不用重启。
- 想几个号同时用,从卡片上 “打开终端”,那个终端固定用该卡片的账号。
- 卡片和授权中心会显示每个号的套餐与剩余额度。
- 不按额度自动轮换账号,也不提供订阅共享功能。
聚合模式(v4.0.0 起)适合 “同一个任务想换不同模型跑” 的场景:多家供应商的模型同时出现在模型选择器里,选谁就发给谁,不用离开客户端。需要注意两点:它是手动开启的,且不提供故障转移;会话中途换模型后,新模型要重建提示词缓存,第一轮成本会更高。
七、数据放在哪,怎么防丢
| 项目 | 位置 / 机制 |
|---|---|
| 核心数据库 | ~/.cc-switch/cc-switch.db |
| 界面设置 | ~/.cc-switch/settings.json |
| 自动备份 | ~/.cc-switch/backups/,官方口径保留最近 10 个 |
| 首次改写备份 | ~/.cc-switch/backups/live-first-write/ |
| 导出包 | 形如 cc-switch-export-{timestamp}.sql |
| 写入方式 | SQLite 加原子写入,v4.0 起只替换关键字段 |
| 云同步 | WebDAV 或常见云盘文件夹 |
一条安全提醒:官方明确说明,任何向你收费、要求充值或索取登录凭据的 “CC Switch” 网站或客户端都是假的;下载只认 ccswitch.io 与 GitHub Releases。另外,官方只提供桌面版,没有官方命令行版,社区另有第三方 CLI 项目,使用前需自行评估。
八、适合谁,不适合谁
适合
- 同时使用 Claude Code 和 Codex,且经常在不同服务商、不同 Key 之间切换的开发者。
- 需要把 MCP、提示词、Skills 在多个 CLI 之间保持一致的团队。
- 想集中查看 Token 用量与花费的个人或小组。
- 有多个 Claude 官方订阅账号,需要按项目分号使用的用户。
不适合
- 只用一款 CLI、只用一个服务商、从不换配置的人,收益有限。
- 纯服务器或 SSH 环境:官方只有桌面版,没有图形界面的机器用不了。
- 期待它替代模型本身的人:CC Switch 不是推理端点,它只负责写配置、做路由。
九、结论
CC Switch 的价值不在于 “又一个 AI 工具”,而在于把 AI 编程工具链里最琐碎的一层 —— 配置管理 —— 做成了一个可切换、可备份、可追踪的桌面控制面。它让 Claude Code 和 Codex 不再各自维护一套 JSON 和 TOML,也让多服务商、多账号、多扩展的日常操作从 “翻文档、改文件、重开会话” 变成 “点一下、确认一下”。对重度使用 AI 编程 CLI 的人来说,这类工具省下的不是一次配置的时间,而是每天反复切换时累积的注意力。
【常见问题】
问题 1:CC Switch 支持哪些 AI 编程工具?
回答 1:截至 v4.0.21,CC Switch 官方 README 列出 13 款受管客户端,包括 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi、MiniMax Code、Kimi Code、Oh My Pi 和 Antigravity CLI,其中 Claude Code 与 Codex 是功能最完整的两条主线。
问题 2:CC Switch 切换服务商后需要重启终端吗?
回答 2:CC Switch 切换服务商后,Claude Code 通常支持热切换,但已在运行的旧会话可能仍走旧节点,保险做法是关掉重开;Codex CLI 需要重开终端,Codex 桌面版需要完全退出再打开,聚合模式下改动模型列表后也要彻底重启。
问题 3:CC Switch 会保存我的 API Key 和账号令牌吗?
回答 3:CC Switch 会为每个服务商独立保存配置,数据库在~/.cc-switch/cc-switch.db;Claude 官方订阅账号的令牌只留在本机 Claude Code 的存储位置,不上传、不写入 CC Switch 数据库,CC Switch 只记录邮箱、组织、套餐和登录过期时间这类账号资料。
问题 4:CC Switch 的聚合模式是什么,和普通切换有什么区别?
回答 4:CC Switch 的聚合模式把多家服务商的模型放进同一个模型选择器,选哪个模型就把请求发给哪家,适合在同一任务里对比不同模型;普通切换是一次只有一份配置生效,聚合模式则是多份配置同时可选,但目前只支持 Claude Code 和 Codex。
问题 5:CC Switch 配置写坏了怎么恢复?
回答 5:CC Switch 首次改写某个工具的配置文件前会备份到~/.cc-switch/backups/live-first-write/,日常自动备份在~/.cc-switch/backups/ 并保留最近 10 个;也可以用设置里导出的 cc-switch-export-{timestamp}.sql 恢复,导入前建议先再导出一份当前配置。
【数据来源】
[2026-11-02](CC Switch 官方文档)CC Switch
[2026-10-27](CC Switch 官网下载安装配置教程(含 CLI))QCode 文档
[2026-10-26](CC Switch v4.0.21 更新日志)CC Switch 官方更新日志
[2026-08-18](CC Switch — One Desktop Switchboard for AI Coding CLIs)CC Switch 官网
【免责声明】
本文为 CC Switch 桌面配置管理工具的公开资料整理与使用科普,支持客户端、版本功能、安装方式、数据存储位置均以官方文档、更新日志与 GitHub Releases 为准,后续版本可能调整。文中不构成软件采购、账号共享或投资建议;使用第三方 API 中转服务前请自行核对合规性与服务条款,API Key 等凭据请妥善保管。
