> ## Content Index
> Fetch the complete content index at: https://orbiorbi.com/news/llms.txt
> Use this file to discover other available public pages before exploring further.

# CC Switch 更新了：聚合模式配置与使用指南
- URL: https://orbiorbi.com/news/cc-switch-juhe-shiyong-zhinan/
- Published: 2026-10-21T20:54:39.000Z
- Updated: 2026-10-21T20:54:39.000Z
- Description: CC Switch 4.0 新增聚合模式，让多家供应商的模型出现在同一个客户端列表里。本文带你从更新备份、添加模型到实际切换，并讲清默认供应商、重启和故障恢复。
- Author: Orbis News
- Tags: API 接入与排障

## 一、先看效果：这篇要完成什么？

**目标：把两家可用供应商放进同一个客户端，各完成一次请求，再能恢复直连。**

CC Switch 4.0 新增聚合模式：你在 Claude Code 或 Codex 里选模型，请求便发给对应供应商，不用每次回 CC Switch 切换。

![Codex 模型选择器同时显示不同供应商的模型](https://orbiorbi.com/news/content/images/2026/10/02-codex-model-picker.png)

*看模型名后面的供应商。可选模型取决于已配置的供应商。*

| 模式 | 适合什么      | 要记住什么           |
| -- | --------- | --------------- |
| 直连 | 日常用一家     | 客户端直连供应商        |
| 路由 | 接口转换、故障转移 | 需要本地转发服务        |
| 聚合 | 在客户端选多家模型 | 按你的选择发送，不自动故障转移 |

本文核查于 2026 年 10 月 22 日，最新正式版为 v4.0.18。聚合只支持 Claude Code 和 Codex，两个应用分别配置。

## 二、安装与更新

### 1\. 先备份，再更新

- 等运行中的任务完成。
- 打开“设置→数据”，导出 SQL，并保留客户端原配置。
- 到“设置→关于”检查更新；新用户从[官方页面](https://ccswitch.io/download?ref=orbiorbi.com)下载安装。

Windows 选对应架构 MSI；Mac 选 DMG，打开后拖到“应用程序”。

**成功标志：** 新版本能打开，原供应商还在。

4.0 改变了数据库结构，升级前自动备份位于`.cc-switch/backups/`。旧程序未必读得了新数据库，回退需匹配备份，不能只覆盖安装包。

### 2\. 可选：agent 一句话安装

> 请按 https://github.com/farion1231/cc-switch 官方说明检查系统、备份已有配置并安装或升级最新稳定版，保留登录与自定义设置，不自动开启聚合；完成后报告版本、备份位置和客户端是否满足要求。

这需要有本地执行能力的 agent；网页登录和系统授权仍可能要本人操作。

### 3\. 检查客户端与账号

- 在 CC Switch“应用”页查看客户端版本。
- Claude Code 须≥2.1.243；终端运行`claude --version`可核对，原生安装可用`claude update`更新。
- 官方账号先在对应客户端登录：Claude Code 运行 `claude` 后按提示登录；Codex 运行 `codex`，选择 **Sign in with ChatGPT** 完成授权。
- 用 `/status` 核对当前配置，发一条短消息确认官方路线可用；API 路线也应分别验证。
- 先理解下表的账号限制，再将 Orbis 作为其中一家 API 服务接入。

![应用管理页显示各工具的当前版本和升级按钮](https://orbiorbi.com/news/content/images/2026/10/apps-zh.png)

*只检查自己要用的工具。图里的版本是截图当时状态。*

| 账号情况              | 能否进入本文练习    |
| ----------------- | ----------- |
| 只有 Claude 官方订阅    | 暂不支持聚合，继续直连 |
| Codex 官方账号＋API 服务 | 官方账号必须设为默认  |
| 两家已支持的 API 服务     | 各自配置和验证后添加  |

**成功标志：** 客户端版本满足要求，两家服务都有实际使用权限。

## 三、配置聚合

### 4\. 接入 Orbis，再给每家选模型

- 登录 [Orbis](https://orbiorbi.com/?ref=orbiorbi.com)，打开下表对应模型页，选择线路并获取 Key。
- 在线路详情打开“快速接入”→选 Key→“工具接入”→Codex CLI 或 Claude Code→“填入 CC Switch”。核对后确认导入。
- **Key 绑定线路**，不靠更改模型 ID 切换线路。导入链接含 Key，不要分享。完整入口见 [Orbis 快速开始](https://orbiorbi.com/docs/quickstart/?ref=orbiorbi.com)。

| 客户端         | 模型与线路                                                                                                                      | 自定义配置所需信息                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Codex       | [GPT 6.1 Sol](https://orbiorbi.com/pricing/gpt-6.1-sol?catalogKey=model%2F91&ref=orbiorbi.com)，GPT · HA                    | 地址 https://api.orbiorbi.com/v1；OpenAI Responses；模型 gpt-6.1-sol     |
| Claude Code | [Claude Haiku 5.5](https://orbiorbi.com/pricing/claude-haiku-5-5?catalogKey=model%2F112&ref=orbiorbi.com)，Claude Code · AH | 地址 https://api.orbiorbi.com；Anthropic Messages；模型 claude-haiku-5-5 |

模型

[GPT 6.1 Sol](https://orbiorbi.com/pricing/gpt-6.1-sol?catalogKey=model%2F91&ref=news-cc-switch-juhe-shiyong-zhinan)`gpt-6.1-sol`

查看本教程使用的模型及对应线路接入信息。

体验

不能自动导入时：左侧选对应客户端→“添加供应商”→“自定义配置”，按上表填写。Codex 的 Key 对应编辑器 `OPENAI_API_KEY`，客户端 `wire_api` 保持 `responses`；Claude 用 `ANTHROPIC_AUTH_TOKEN`，地址写 `ANTHROPIC_BASE_URL`，并将 `ANTHROPIC_MODEL` 与 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 都设为 `claude-haiku-5-5`，让主模型与后台小模型保持在该线路授权范围内。保持“完整 URL”关闭，不自行拼请求路径。Orbis 卡片是你添加的配置，不假定软件自带预设。

模型

[Claude Haiku 5.5](https://orbiorbi.com/pricing/claude-haiku-5-5?catalogKey=model%2F112&ref=news-cc-switch-juhe-shiyong-zhinan)`claude-haiku-5-5`

查看本教程使用的模型及对应线路接入信息。

体验

然后进入本客户端顶部“聚合”。**点击标签只是查看页面。** 编辑 Orbis 卡片的“模型列表”：

- 点“获取模型列表”，搜索并勾选当前线路支持的模型，点“添加所选模型”。
- 如果线路没提供列表接口，点“手动添加”，填表中的真实模型 ID；显示名可写易认的名字。
- 第二家供应商也按其文档配好地址、Key 和模型，先各保留一个模型。

**成功标志：** 两张卡片都有正确模型。两个 Orbis 模型仍是一家服务；若只有 Orbis，可以先练多模型切换，尚未完成“两家供应商”的目标。

自动补全只填写空缺参数，不覆盖已有值；把上下文窗口填大，不会提升真实模型能力。

### 5\. 加入名单，设默认，开启

- 在“可添加”区域点卡片的“添加”。
- 点“切换到聚合模式”。
- 确认框内核对默认供应商和模型数量，确认开启。

![聚合页面显示当前默认供应商、已添加名单和重启提示](https://orbiorbi.com/news/content/images/2026/10/01-cc-switch-aggregation.png)

*依次看顶部“聚合生效中”、默认卡片、已添加数量。示例中的品牌和余额不构成推荐。*

默认供应商负责没有明确指定聚合线路的普通请求。Codex 的 OpenAI Official 只能设默认，不能作为普通成员添加。

**成功标志：** 顶部显示“聚合生效中”。保存供应商≠加入名单≠开启聚合，三步都要完成。

## 四、第一次使用：两轮请求验证

### 6\. 让客户端读到新列表

| 客户端         | 名单或模型配置变化后              |
| ----------- | ----------------------- |
| Codex 桌面版   | 彻底退出再打开；Mac 按 Command+Q |
| Codex CLI   | 按提示重启守护进程，再打开 CLI       |
| Codex 编辑器插件 | 重开编辑器窗口                 |
| Claude Code | 列表通常立即生效；按提示重选模型        |

守护进程是共用后台程序，重启可能打断其他任务。已经加载的列表里换模型，不用每次重启。

**成功标志：** 客户端能看到刚加入的模型，而非只剩旧列表。

### 7\. 选第一家，再换第二家

- 选第一家，发送：

> 请用五句话解释备份与同步的区别，只回答，不操作文件。

- 收到回答后，在同一对话换第二家，发送：

> 检查上面的解释，指出两处新手容易误解的地方，只回答。

Claude Code 用户输入`/model`打开选择器：

![Claude Code 的模型列表标明模型名称与供应商](https://orbiorbi.com/news/content/images/2026/10/03-claude-code-model-picker.png)

*按供应商标注选条目，不需要自己编写 ccs-前缀。*

**成功标志：** 两家都能返回回答，并能结合调用记录核对线路。

## 五、进阶使用与恢复

### 8\. 按任务阶段切换

- 先用熟悉的模型讨论方案，再换另一模型检查遗漏。
- 切换前确认历史对话适合发给下一家。
- 长对话避免频繁切换：新模型可能重建缓存，第一轮费用更高。

**成功标志：** 知道换模型的目的，也确认下一家支持当前任务需要的图片或工具能力。

聚合期间保持 CC Switch 运行。熟练后再配置子 agent 分工，先保留跨供应商兼容设置，不要同时改多个高级选项。

### 9\. 给同一家供应商增加模型

- 编辑供应商，在“模型列表”里重新获取列表，勾选新增模型。
- 取不到列表时，点“手动添加”，填写服务支持的真实模型 ID。
- 保留容易辨认的显示名，并核对默认模型；保存后按第 6 步刷新客户端。

一张 Orbis 卡可以放多个模型，它们仍然来自同一家 API 服务；这不等于多家供应商冗余。模型原厂不同，也不代表接入线路不同。

**成功标志：** 新旧模型都能在选择器里找到，调用记录仍归到正确供应商。自动补全只补空缺信息，能力以当前服务实际支持为准。

### 10\. 让 Codex 子 agent 使用另一模型

- 聚合页右上角齿轮→“聚合设置”。
- 在“子代理模型”选择已经发布到聚合列表的模型；推理强度先保留“模型默认”。
- 跨供应商时保留“聚合模式下子 agent 用经典工具”，新开一个对话再使用。

这是子任务的默认模型，主 agent 显式指定时仍以任务设置为准。要撤销，选“跟随主模型”。不同供应商之间的任务内容会传给相应服务，先确认数据适合共享。

**成功标志：** 新对话的子任务按所选配置运行。若出现无法解密任务的错误，检查经典工具开关，并按提示重启 Codex；不要只换 API Key。

### 11\. 出错先恢复直连

- 点“回到直连”，选择此前成功使用的供应商。
- 按提示重启客户端，再发送短请求。
- 要移除当前默认时，先把另一家设为默认。

![主界面处于直连模式，卡片显示使用中](https://orbiorbi.com/news/content/images/2026/10/main-zh.png)

*这是 Claude Code 的直连示例。Codex 用户仍在 Codex 页操作，检查相同的模式与当前供应商状态。*

**成功标志：** 直连再次收到回答。正常退出 CC Switch 会恢复直连；强制结束进程后，应重开程序核对状态。

| 问题          | 先查哪里                   |
| ----------- | ---------------------- |
| 名单有卡片，没有模型  | 模型列表是否填写、是否已加入名单       |
| Codex 仍是旧列表 | 是否彻底重载，CLI 是否重启守护进程    |
| 一家服务失败      | Key、模型 ID、权限和额度；手动换另一家 |
| 移除后仍报错      | 重新选现存模型，别沿用旧条目         |

仍找不到原因时，在“设置→数据→应用诊断日志”打开日志，按失败时间找错误；顶部有环境变量冲突提示时，先核对旧地址是否覆盖新配置，别直接清空全部变量。导出日志前遮住密钥和请求内容。

需要导入升级前 SQL 时，先备份当前数据库。导入会整体覆盖供应商、MCP、提示词与用量等记录。完成“两家各请求一次＋恢复直连”，再逐步增加供应商。

## 参考与图片

操作依据[官方聚合手册](https://github.com/farion1231/cc-switch/blob/main/docs/user-manual/zh/4-proxy/4.6-aggregation.md?ref=orbiorbi.com)、[官方图文指南](https://github.com/farion1231/cc-switch/blob/main/docs/guides/aggregation-mode-guide-zh.md?ref=orbiorbi.com)。组织参考[QCode](https://qcode.cc/cc-switch-4-aggregate-mode?ref=orbiorbi.com)、[Gunzo](https://gunzo.cc/content/how-to-use-cc-switch?ref=orbiorbi.com)与[XieCoding](https://xiecoding.cn/view/855.html?ref=orbiorbi.com)，旧版事实未照搬。

图片为官方文档原图，MIT 许可，Copyright (c) 2025 Jason Young；品牌归各权利人。