CC Switch 完全指南：一键切换 Claude Code / Codex / Gemini 的 API 供应商
CC Switch 完全指南：一键切换 Claude Code / Codex / Gemini 的 API 供应商
引言
用 Claude Code、Codex、Gemini CLI 这类 AI 编程工具时，国内开发者常会遇到一个共同的麻烦：想在官方模型和各种国产/中转模型之间来回切换，就得手动改配置文件——多个 API Key、多个 Base URL 反复折腾，改错一个字符整套环境就崩了。
CC Switch（也写作 cc-switch）正是为解决这个痛点而生的开源桌面工具。它把 Claude Code、Codex、OpenCode、Gemini CLI 四款工具的配置切换、MCP 服务器、系统提示词、Skills 统一收进一个图形界面，点一下就能换供应商。目前已在 GitHub 收获 14.5K Star。
本文将带你完成 CC Switch 的安装、配置和日常使用，并梳理常见的踩坑点。
一、CC Switch 是什么
CC Switch 是一个跨平台桌面应用，核心定位是「AI CLI 工具的配置管理中心」。它的价值可以归纳为三点：
- 统一管理：一个界面同时管理 Claude Code、Codex、Gemini CLI 等多款工具的配置
- 一键切换：在不同 API 供应商（官方 Claude、DeepSeek、GLM、ModelScope 等）之间秒切，无需手动改配置文件
- 配套增强：可视化管理 MCP 服务器、Skills、系统提示词，还能看 Token 用量统计
它解决的痛点非常实际：当你既想用官方 Claude 模型，又想在预算紧张时切到便宜的国产模型，传统做法是手动编辑 ~/.claude/settings.json，而 CC Switch 把这一切变成了点击操作。
二、安装 CC Switch
2.1 下载安装包
前往 GitHub Releases 页面下载对应平台的安装包：
https://github.com/farion1231/cc-switch/releases/latest
提供 Windows、macOS、Linux 三个平台的版本。
macOS 用户也可以通过 Homebrew 安装：
brew tap farion1231/ccswitch
brew install --cask cc-switch
2.2 各平台安装注意事项
| 平台 | 注意事项 |
|---|---|
| Windows | 会弹 SmartScreen 提示，点「更多信息」→「仍要运行」即可；也可下载 .zip 便携版解压直接运行 |
| macOS | 因作者无 Apple 开发者账号，可能提示「未知开发者」，需到「系统设置 → 隐私与安全性」点「仍要打开」 |
| Linux | 直接运行对应的安装包即可 |
⚠️ Windows 特别提示：Windows 版本已禁用「一键安装」CLI 工具的功能（避免协议处理器副作用）。如需安装 Claude Code 等工具，请先手动安装，再用 CC Switch 管理。
2.3 首次启动
启动后 CC Switch 会做两件事：
- 自动检测已安装的 CLI 工具，并尝试导入它们现有的配置
- 在系统托盘生成 CC Switch 图标，方便随时唤起
主界面顶部是应用切换栏，点击对应图标（Claude Code / Codex / Gemini CLI）即可切换当前正在管理的工具。
三、配置供应商（核心三步）
整个接入流程可以浓缩成一句话：装 cc-switch → 加供应商填好地址和 Key → 点「使用」。
3.1 添加第一个供应商
- 在主界面点击「Add Provider」（添加供应商）
- 你有两个选择：
- 使用预设模板：CC Switch 内置了 DeepSeek、GLM、ModelScope 等众多供应商的模板，选中后只需填 API Key
- 手动输入：自己填写 API Key + Base URL（基地址）
3.2 启用配置
填好后点击「Enable」（启用），程序会自动把配置写入对应 CLI 的配置文件：
- Claude Code →
~/.claude/settings.json - Codex →
~/.codex/ - 以此类推
整个过程无需手动编辑任何配置文件。
3.3 一个常见的配置坑
⚠️ Base URL 末尾不要加斜杠！
如果 Base URL 写成
https://api.example.com/（末尾带/），Claude Code 在拼接 API 路径时会出现双斜杠（//），导致请求报错。正确写法是https://api.example.com。
四、配置生效与热切换
切换供应商后，配置立即写入，但是否立即生效取决于工具：
- Claude Code 支持热重载——但有个细节要注意
- 其他工具可能需要重启
Claude Code 切换后「没反应」？这不是 Bug
很多人会遇到这样的情况：在 CC Switch 里切换了供应商，但正在运行的 Claude Code 好像没变。
原因：Claude Code 是在启动时读取配置文件的。CC Switch 直接修改了 settings.json，但当前已经运行的会话不会重新加载。
解决：把当前 Claude Code 会话关掉重开，下次 API 调用就会自动读取新配置了。
五、主要功能模块
CC Switch 不止是「换 Key」，它还集成了一整套 AI 工具管理能力。
5.1 MCP 服务器管理
在「MCP」面板中可视化添加、编辑、删除 MCP（Model Context Protocol）服务器。配置会自动同步到对应的 CLI 工具，还支持从已安装的应用一键导入现有 MCP 配置。
对于经常配置 MCP 工具的开发者，这个功能省去了手动编辑 JSON 的麻烦。
5.2 Skills 管理
Skills 是 Claude Code 的提示词增强功能。CC Switch 支持从 GitHub 仓库安装 Skills，内置了 baoyu-skills 等预设仓库，点几下就能给 Claude Code 装上技能包。
5.3 用量统计
「用量」页面展示 Token 消耗统计，支持：
- 自动刷新
- 缓存命中率分析
- 按模型和 Provider 分类查看费用
对于按 Token 计费的中转 API，这个面板能帮你心里有数。
5.4 会话历史与备份
- 「会话」页面可浏览全部工具的历史对话，支持目录导航和会话内搜索
- CC Switch 会定期自动备份数据库，设置中可查看、重命名、删除及手动创建备份
5.5 推荐的设置开关
为获得最佳体验，建议在「设置 → 窗口行为」中启用以下开关：
| 开关 | 作用 |
|---|---|
| 开机自启 | 系统启动后自动运行 |
| 静默启动 | 启动时不弹主窗口，直接进托盘 |
| 应用到 Claude Code 插件 | 把 VS Code 等编辑器中的 Claude Code 扩展供应商一键同步 |
| 跳过首次运行安装确认 | 减少弹窗 |
| 关闭时最小化到托盘 | 点 × 不退出，留在后台 |
六、配置文件位置与编辑器集成
6.1 配置写在哪
CC Switch 操作的是全局配置：
- 配置写入
~/.claude/profiles/目录（如~/.claude/profiles/default.json） - 切换时自动覆盖
~/.claude/settings.json
6.2 关于 VS Code / Cursor 等编辑器
很多人疑惑：用 VS Code 内置终端跑 claude，需要单独装插件吗？
答案是不需要。 原因在于：
- CC Switch 改的是
~/.claude/settings.json这份全局配置 - VS Code 内置终端继承 shell 环境，跑
claude时用的是同一份 settings
所以 Cursor、Windsurf、Zed 等编辑器的内置终端行为完全一致。CC Switch 是后台层的配置管理，不依赖任何具体编辑器。
七、常见问题排查
Q1：中文用户名导致报错
原因：数据库文件路径走的是 %USERPROFILE%\.cc-switch\cc-switch.db，Windows 中文用户名路径有时会出错。
解决：
- 最干净的解法是换一个英文用户名
- 或者使用便携版（
.zip），把数据放在英文路径下绕开问题
Q2：GitHub 源访问慢/失败
原因：CC Switch 内置的 GitHub 源（下载 Skills、检查更新等）对国内网络不太友好。
解决：配置代理，或在网络条件好的时候操作。
Q3：切换后 Claude Code 没生效
参见第四节——关闭当前会话重开即可，这是 Claude Code 启动时读配置的机制决定的，不是 Bug。
Q4：Base URL 报双斜杠错误
参见 3.3——Base URL 末尾不要加斜杠。
八、总结
CC Switch 把多款 AI CLI 工具的配置管理从「手动改 JSON」变成了「图形界面点一点」，对于需要在多个供应商间切换的开发者来说，是一个实打实提升效率的工具。关键要点回顾：
- 安装：从 GitHub Releases 下载，Windows 注意 SmartScreen，macOS 注意未知开发者提示
- 配置：Add Provider → 选模板或填 Key/URL → Enable，三步搞定
- 避坑：Base URL 末尾别加斜杠；切换后 Claude Code 要重开会话
- 进阶：用好 MCP 管理、Skills 安装、用量统计等配套功能
随着 AI 编程工具生态的快速发展，像 CC Switch 这样的「配置管理层」工具会越来越重要。如果你也在多个模型供应商之间反复横跳，不妨试试它。
项目地址：https://github.com/farion1231/cc-switch
本文由 Claude Code + cnblogs MCP Server 协作发布。
浙公网安备 33010602011771号