CC Switch 使用教程
从官方渠道安装 CC Switch，给 Claude Code、Codex、OpenCode 等一键切换 API 供应商，理解路由模式写进配置文件的内容，以及 key 存储和第三方中转的风险，均链接官方文档。
核验日期：2026-10-20。本文依据 CC Switch 官方 README 和用户手册整理（核验时为 v4.0.16），本站尚未实测。CC Switch 更新很快，以文中链接的官方页面为准。
CC Switch 是一个开源桌面应用（MIT 许可证），用来管理 Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes、Pi 和 MiniMax Code 的配置：一键切换 API 供应商，统一管理 MCP 服务、Skills 和提示词文件，不用再手改 JSON / TOML / YAML。它本身不是 Agent，所以本站目录不收录它，但它是很多人用这些 Agent 时离不开的工具。本文讲安装、切换供应商、路由模式，以及用之前需要知道的几个风险。
第一步：从官方渠道下载
官方说明唯一官方网站是 ccswitch.io，安装包在 GitHub Releases。不要从其他网站下载，这类工具会接触你所有的 API key。
| 系统 | 安装方式 | 要求 |
|---|---|---|
| Windows | 下载 CC-Switch-v{版本}-Windows.msi，或免安装的 Portable.zip |
Windows 10 及以上 |
| macOS | brew install --cask cc-switch，或下载 .dmg |
macOS 12 及以上，Apple 芯片和 Intel 都支持，已签名公证 |
| Linux | 下载 .deb、.rpm 或 .AppImage；Arch 用 paru -S cc-switch-bin |
glibc 2.35+ 和 WebKitGTK 4.1，如 Ubuntu 22.04+ |
CC Switch 只有图形界面版本。服务器或纯 SSH 环境可以用社区维护的 CC Switch CLI，它不是官方项目。
第二步：添加和切换供应商
- 第一次打开时，CC Switch 会把你现有的 Claude Code、Codex、Gemini CLI、Grok Build 配置导入为名叫
default的供应商，并为每个工具加一个官方登录选项，原来的配置不会丢。 - 在左侧选中要管理的工具，点右上角“+”，从 90 多个预设里选一个供应商并填 key，或者自己填自定义配置。
- 点“启用”切换。Claude Code 不用重启；Codex、Gemini CLI、Grok Build 要重启终端或工具；Claude Desktop 要完全退出再打开。
- 想回到官方登录（例如 Claude 订阅或 ChatGPT 账号），在列表里切到内置的“Claude Official”“OpenAI Official”等，重启工具后按它自己的登录流程走。
OpenCode、OpenClaw、Hermes、Pi 和 MiniMax Code 是“共存”模式：点“添加”会把多个供应商同时写进工具自己的配置，再到工具里选模型。
切换只替换关键字段：地址、key、模型名和协议。你自己加的插件、hooks、MCP 和注释不会动。第一次改写某个工具的配置前，原文件会备份到 ~/.cc-switch/backups/live-first-write/。见 官方快速上手与 FAQ。
第三步：路由模式（在 Claude Code 里用 GPT，在 Codex 里用 Claude）
Claude Code、Codex、Gemini CLI、Grok Build 的页面顶部有“直连 / 路由”切换。开启路由后：
- 工具的请求先发到本机的 CC Switch（默认
http://127.0.0.1:15721），再由它转发给你选的供应商，并在 Anthropic、OpenAI、Gemini 几种 API 格式之间自动转换。所以开启后配置文件里只会看到本机地址和占位 keyPROXY_MANAGED，这是正常的。 - 可以给每个工具配一个故障切换队列：请求失败时自动换下一个供应商。
- 想在 Claude Code 里用只提供 OpenAI 格式接口的服务（包括很多本地模型服务），必须开路由，并在供应商的高级选项里把“上游格式”设为对应的格式。
- 路由要求 CC Switch 一直在运行。退出 CC Switch 时，它会先把配置写回直连供应商。
- 官方订阅登录（如 Claude Official）不能走路由，Codex 的 OpenAI Official 例外。
见 官方路由说明。
用之前要知道的几件事
- 你的 key 都存在本机：供应商、key、MCP 和用量记录在
~/.cc-switch/cc-switch.db里；ChatGPT、Copilot、Grok 的登录凭据在同目录的几个*_auth.json文件里。开启云同步（WebDAV、S3）时，这些数据会同步到你选的存储上，要确认那个存储足够安全。 - 第三方中转的风险由你承担：CC Switch 的 README 里有大量 API 中转服务的赞助广告，号称比官方便宜很多。经过中转时，你的代码和提示词会经过该服务商；用之前请确认它是否符合原模型厂商的服务条款，以及它怎么处理你的数据。本站不推荐任何中转服务。
- “连通性检查”通过不等于能用：它只检查地址是否可达，不会验证 key 和模型名。请求失败时，先查 key、模型名和上游格式。
- 卸载后工具照常能用：CC Switch 总会保留一个在用的配置，所以不能删除正在使用的供应商，要先切到别的再删。
Windows 与 WSL
CC Switch 不会自动识别 WSL。要管理 WSL 里的工具，在“设置 → 应用配置”里把对应工具的配置目录改成 WSL 路径，例如 \\wsl.localhost\Ubuntu\home\<用户名>\.claude。注意：路由模式写入的 127.0.0.1，在 WSL2 默认的 NAT 网络下访问不到 Windows 上的 CC Switch，需要把 WSL 改成镜像网络模式（mirrored）。
常见问题
CC Switch 免费吗？ 免费开源，MIT 许可证，源码在 farion1231/cc-switch。花钱的是你接入的模型服务。
切换后在工具里改的模型为什么又变回去了？ 模型属于供应商的关键字段。在工具里用 /model 改的模型只到下次切换为止；想长期生效，要在 CC Switch 里编辑这个供应商的模型。
CC Switch 能替代 Agent 本身吗？ 不能。它只管理配置，你仍然要先安装 Claude Code、Codex 等工具。安装方法见本站的 Codex 教程、OpenCode 教程 和 Hermes Agent 教程；想先选工具，看 AI 编程 Agent 排行榜。