## 引言：为什么你需要 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 页面](https://github.com/farion1231/cc-switch/releases/latest)
2. 滚动到页面最下方，下载适合自己系统的安装包。Windows 推荐下载 `.msi` 后缀的安装包进行标准安装。
3. 安装后运行 CC-Switch 主程序，界面如下：

   ![CC-Switch 主界面]![ScreenShot_2026-07-03_131827_341.jpg](https://developer.qcloudimg.com/http-save/yehe-6616341/55f86a8ef979bbb5f015f1abb3822886.jpg)


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

#### macOS 用户

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

```bash
# 添加 tap 源
brew tap farion1231/ccswitch

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

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

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

#### Linux 用户

Debian / Ubuntu 系统：

```bash
# 下载 .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 分组]![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/d5a7181f8d9ae64392094a91ac9e30ff.png)


**第二步：新增供应商配置**

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

![选择自定义配置]![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/f9264ed61f0132444467b02a94308d93.webp)


**第三步：获取 CUMOB API 令牌**

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

![创建 API 令牌]![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/59f00471905b95580fdc1b1476eefdf9.webp)


**第四步：填写配置信息**


> **🔥 关键一步：追加环境变量**
>
> CC-Switch 目前**不会自动注入** `CLAUDE_CODE_ATTRIBUTION_HEADER` 变量。在 CC-Switch 的配置模态框里，找到「环境变量」编辑区，追加这一行：
>
> ```text
> CLAUDE_CODE_ATTRIBUTION_HEADER=0
> ```

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

> ```textjson
> {
>   "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 秒。务必添加！

**第五步：启用配置**

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

![启用配置]![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/8d43138d839edb3915fbb9b7f491812b.webp)


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

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

![跳过初次安装确认]![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/6b12a149b97438a995f0f9916b622a21.webp)


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

**第七步：验证配置**

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

---

## 第三部分：Codex 配置

### 3.1 配置步骤

**第一步：切换至 Codex 分组**

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

![切换至 Codex 分组]![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/15ba939a4e5d88de82c276a5e4779218.webp)


**第二步：获取 CUMOB API 令牌**

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

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

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

在CC-Switch主界面右上角点击 **「+」** 按钮，选择添加新供应商：
![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/8f1baef7a79eccc556476371f8036512.webp)
再添加供应商界面填写 API 请求地址 和 上一步复制的 API Key等信息后点击保存按钮。
![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/cef8e0b33fc4a6924019a34d6b1b0936.webp)

**第四步：启用并验证**

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

![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/314eb2d5ccc1561fc493d9fca9e918c0.webp)

> **补充提醒:这个归属头机制本身是 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」：

![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/0504de5d4e60ddfc611027a369125632.webp)


**第二步：获取 CUMOB API 令牌**

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

**第三步：配置并启用**

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

![image.png](https://developer.qcloudimg.com/http-save/yehe-6616341/8b3b1555f12dacc871542c8ce7792a64.webp)


**第四步：验证**

在终端运行 `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 这个大模型路由平台。核心价值在于：

| 传统方式 | 使用 CC-Switch |
|---------|---------------|
| 手动定位多个配置文件 | 一个图形界面统一管理 |
| 逐个修改 JSON / TOML / INI | 一键切换供应商 |
| 配置格式错误导致启动失败 | 预设模板自动填充 |
| MCP 和 Skills 各自独立配置 | 一处配置，多工具同步 |

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

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

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

开发工具

人工智能

职业发展

CC-Switch是一款跨平台AI编程工具管理软件，支持Windows/macOS/Linux系统。它能统一管理ClaudeCode、Codex、GeminiCLI等工具的API配置、MCP服务器和提示词，提供图形化界面操作。通过一键切换供应商、可视化配置管理、系统托盘快捷操作等功能，解决多工具配置繁琐问题，提升开发效率。支持CUMOBAPI接入，优化缓存性能，降低API调用成本。

代码解释

服务器

数据库

OpenClaw

AI编程

Windows

路由

Ubuntu

Debian

GitHub

Linux

腾讯云大模型Token Plan个人版28元/月起

tokenhub

2026上云采购 | AI焕新·智启新局

apigw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

CC-Switch是一款跨平台AI编程工具管理软件，支持Windows/macOS/Linux系统。它能统一管理ClaudeCode、Codex、GeminiCLI等工具的API配置、MCP服务器和提示词，提供图形化界面操作。通过一键切换供应商、可视化配置管理、系统托盘快捷操作等功能，解决多工具配置繁琐问题，提升开发效...

CC-Switch 完全上手教程：从供应商切换器到 AI CLI 一体化管理平台-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐