CC-Switch 完全上手教程：从供应商切换器到 AI CLI 一体化管理平台

引言：为什么你需要 CC-Switch？

假如你同时在使用 Claude Code、Codex 和 Gemini CLI 这三个 AI 编程工具，每次想换个模型供应商，就得手动翻出各自的配置文件来改——Claude Code 要改 settings.json，Codex 要调 config.toml，Gemini CLI 又有自己的路径。改完一个忘了另一个是常有的事，配置文件格式写错了还会导致工具启动失败。

CC-Switch 就是为解决这个痛点而生的。它是一个开源的跨平台桌面工具，支持 Windows、macOS 和 Linux，能够用一个图形界面统一管理 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等主流 AI 编程工具的供应商配置、MCP 服务器、Skills 扩展和系统提示词 。你可以把它理解成一个「AI 编程工具的总控台」：

• 一键切换 API 配置：在多个 API 提供商之间快速切换，无需手动改文件
• 可视化配置管理：通过图形界面轻松管理所有配置
• MCP 服务器管理：集中管理 Model Context Protocol 服务器
• 系统托盘快捷操作：通过托盘菜单快速切换供应商，无需打开主界面

第一部分：准备工作（通用步骤）

在配置任意 CLI 客户端之前，请先完成本部分的软件下载与环境检查。

1.1 下载 CC-Switch

Windows 用户

1. 打开 CC-Switch 的 GitHub Release 页面
2. 滚动到页面最下方，下载适合自己系统的安装包。Windows 推荐下载 .msi 后缀的安装包进行标准安装。

3. 安装后运行 CC-Switch 主程序，界面如下：

   ![CC-Switch 主界面]

⚠️ Windows 小贴士：如果系统弹出 SmartScreen 安全提示，点击「更多信息」→「仍要运行」即可。如果不想安装，也可以下载 .zip 便携版，解压后直接运行 。

macOS 用户

macOS 推荐使用 Homebrew 安装，打开终端依次运行：

# 添加 tap 源
brew tap farion1231/ccswitch

# 安装 CC-Switch
brew install --cask cc-switch

安装完成后，在「启动台」或「应用程序」文件夹中找到 CC-Switch 并启动。

⚠️ macOS 小贴士：首次打开可能提示「无法验证开发者」，去「系统设置」→「隐私与安全性」中点击「仍要打开」即可 。

Linux 用户

Debian / Ubuntu 系统：

# 下载 .deb 包（请将 x.x.x 替换为实际版本号）
wget https://github.com/farion1231/cc-switch/releases/latest/download/cc-switch_x.x.x_amd64.deb

# 安装
sudo dpkg -i cc-switch_x.x.x_amd64.deb

其他发行版也可使用 AppImage 通用格式，下载后赋予执行权限即可运行 。

1.2 环境检查

在开始配置之前，请确认以下环境已就绪：

1. Node.js：各 CLI 工具均依赖 Node.js 环境
2. 各 CLI 工具已安装：Claude Code、Codex、Gemini CLI 中至少有一个已安装
3. 配置目录存在：各工具的配置目录已生成

💡 如果你已确认以上环境无误，可以直接进入对应客户端的配置章节。如果还不确定，建议先完成环境检查。

第二部分：Claude Code 配置

2.1 前置提醒

⚠️ 重要提示

CUMOB API 的 Claude 系列分组中，claude-awsq-满血 与 Kiro-Claude-高缓存 支持第三方接入，可在 CC-Switch 中正常配置与使用。配置是否生效，请以 Claude Code 内的实际对话结果为准。

2.2 配置步骤

第一步：选择分组

打开 CC-Switch 软件，在顶部分组条中将分组切换至「Claude」：

![切换至 Claude 分组]

第二步：新增供应商配置

点击右上角的 「+」 按钮，在供应商分组中选择「自定义配置」：

![选择自定义配置]

第三步：获取 CUMOB API 令牌

在 CUMOB API 平台中，创建 CC 分组的令牌，复制 API Key 到剪切板：

![创建 API 令牌]

第四步：填写配置信息

🔥 关键一步：追加环境变量

CC-Switch 目前不会自动注入 CLAUDE_CODE_ATTRIBUTION_HEADER 变量。在 CC-Switch 的配置模态框里，找到「环境变量」编辑区，追加这一行：

CLAUDE_CODE_ATTRIBUTION_HEADER=0

手动配置 settings.json 也是同样的写法 ：

{
  "env": {
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

这个环境变量是做什么的？
CLAUDE_CODE_ATTRIBUTION_HEADER 是 Claude Code 用来控制归属头注入行为的环境变量。设置 CLAUDE_CODE_ATTRIBUTION_HEADER=0 会告诉 Claude Code 不要在每次 API 请求的系统提示词中插入那段动态生成的归属信息（attribution header）。

补充提醒:这个归属头机制本身是 Anthropic 用来追踪 API 使用来源（如区分 CLI 还是网页端）的手段。关闭它不会影响 Claude Code 的核心功能，但对于频繁调用 API 的开发者来说，不关的代价就是缓存失效带来的额外成本和延迟 。 也是接入第三方中转 API 时最关键的缓存优化开关**——不加的话，Claude Code 2.1.36+ 注入的动态归因标识会让 6.8 万 tokens 的系统提示词每次都缓存失败，实测费用会暴涨约 10 倍，首包延迟从 2 秒变成 17 秒。务必添加！

第五步：启用配置

添加成功后，主界面会显示你配置的分组。在右侧点击「启用」按钮，显示「使用中」即配置完成：

![启用配置]

第六步：跳过初次安装确认

点击左上角「设置」按钮，在通用页面下拉找到 「跳过 Claude Code 初次安装确认」，务必勾选：

![跳过初次安装确认]

这一步可以避免首次启动时弹出登录或初始化引导，让你直接进入对话 。

第七步：验证配置

在终端运行 claude，看到对话界面并能正常回复，即表示配置完成。

第三部分：Codex 配置

3.1 配置步骤

第一步：切换至 Codex 分组

在 CC-Switch 顶部分组条中，将分组切换至「Codex」：

![切换至 Codex 分组]

第二步：获取 CUMOB API 令牌

在 CUMOB API 平台中，创建令牌，复制 API Key。

📌 注意：CUMOB API 对 API Key 做了统一的归一化处理，同一个Key 可通用于 Claude 或 Codex。

第三步：新增并配置供应商

在CC-Switch主界面右上角点击 「+」 按钮，选择添加新供应商：

再添加供应商界面填写 API 请求地址 和 上一步复制的 API Key等信息后点击保存按钮。

第四步：启用并验证

添加成功后点击「启用」，然后在终端运行 codex，看到正常回复即表示配置完成：

**补充提醒:这个归属头机制本身是 Anthropic 用来追踪 API 使用来源（如区分 CLI 还是网页端）的手段。关闭它不会影响 Claude Code 的核心功能，但对于频繁调用 API 的开发者来说，不关的代价就是缓存失效带来的额外成本和延迟 。

也是接入第三方中转 API 时最关键的缓存优化开关——不加的话，Claude Code 2.1.36+ 注入的动态归因标识会让 6.8 万 tokens 的系统提示词每次都缓存失败，实测费用会暴涨约 10 倍，首包延迟从 2 秒变成 17 秒。务必添加！

第四部分：Gemini CLI 配置

4.1 配置步骤

第一步：切换至 Gemini 分组

在 CC-Switch 顶部分组条中，将分组切换至「Gemini」：

![切换至 Gemini 分组]

第二步：获取 CUMOB API 令牌

在 CUMOB API 平台中，创建令牌，复制 API Key。

第三步：配置并启用

点击 「+」 按钮，选择你要调用的 Gemini 系列模型，填写 API Key 后保存并启用：

![Gemini 配置完成]

第四步：验证

在终端运行 gemini，验证能否正常对话：

第五部分：进阶功能

配置好基础接入后，CC-Switch 还有更多强大功能等你探索。

5.1 MCP 服务器统一管理

MCP（Model Context Protocol）是 AI 工具扩展外部能力的标准接口，支持文件读写、数据库访问、网页检索、命令执行等功能 。CC-Switch 提供了一个独立的 MCP 管理面板，支持：

• 可视化新增、编辑、删除 MCP 服务配置
• 一键导入本地已部署工具的存量 MCP 参数
• 支持三类协议：stdio、HTTP、SSE
• 一处编辑，多处同步：配置保存后，所有绑定的 AI 工具同步生效

点击顶部导航栏的「MCP」按钮进入管理面板，使用内置预设模板即可快速添加常用 MCP 服务器（如 fetch、context7、sequential-thinking 等）。

5.2 Skills 扩展管理

Skills 是拓展 AI 工具专属功能的插件。CC-Switch v3.16.3 支持 ：

• 从 GitHub 仓库一键拉取安装
• 导入本地压缩包离线插件
• 插件检索、版本更新、启用/禁用、批量卸载

一次安装 Skills 后，所有关联的 AI 编程工具均可共用，无需重复部署 。

5.3 系统提示词统一管理

不同的 AI 编程工具读取不同的提示词文件——Claude Code 读取 CLAUDE.md，Codex 和 Gemini 各有自己的配置格式。CC-Switch 支持：

• 用项目名称作为标题，配置多份提示词
• 一键开启后自动映射到不同 AI 工具的配置文件中
• 开发前端项目时开启对应的提示词开关，所有工具同步生效

进入「提示词管理」页面即可开始配置。

5.4 系统托盘快捷切换

配置完成后，CC-Switch 会常驻系统托盘。右键点击托盘图标，可以直接在菜单中切换供应商，按应用分组显示（Claude / Codex / Gemini），无需打开主界面即可完成切换 。

第六部分：常见问题排查

Q1：添加供应商后 AI 工具调用无响应？

排查步骤 ：

1. 使用供应商卡片上的「健康检查」按钮验证接口连通性
2. 检查 API Key 是否有多余空格或换行符
3. 确认 Base URL 末尾不要加多余的斜杠 /
4. 确认供应商已点击「启用」（状态显示为「使用中」）
5. 部分工具需要关闭终端重新打开才能加载新配置

Q2：切换后配置没有生效？

1. 退出 AI 工具（Ctrl+C），重新启动
2. 如果还是没生效，关闭终端后重新打开再试
3. 检查是否有系统环境变量覆盖了 CC-Switch 写入的本地配置

Q3：Claude Code 提示需要登录或显示初始化引导？

在 CC-Switch 中打开「设置 → 通用」，开启「跳过 Claude Code 初次安装确认」选项，然后重新启动 Claude Code 。

Q4：Windows 便携版无法识别本地 AI 工具？

便携版无系统注册表读取权限，需要在软件设置页面手动指定工具安装路径，然后重启程序重新扫描配置 。

Q5：macOS 无法打开 CC-Switch？

去「系统设置」→「隐私与安全性」页面，点击「仍要打开」即可 。

总结

通过 CC-Switch，你已经学会了如何统一管理 Claude Code、Codex 和 Gemini CLI 的供应商配置，接入 CUMOB API 这个大模型路由平台。核心价值在于：

配置完成后，你可以在系统托盘中随时切换不同供应商和模型，让 AI 编程工具的使用体验变得丝滑流畅。