CC Switch 聚合模式配置与使用指南

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

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

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

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

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

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

二、安装与更新

1. 先备份，再更新

等运行中的任务完成。
打开“设置→数据”，导出 SQL，并保留客户端原配置。
到“设置→关于”检查更新；新用户从官方页面下载安装。

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 服务接入。

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

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

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

三、配置聚合

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

登录 Orbis，打开下表对应模型页，选择线路并获取 Key。
在线路详情打开“快速接入”→选 Key→“工具接入”→Codex CLI 或 Claude Code→“填入 CC Switch”。核对后确认导入。
Key 绑定线路，不靠更改模型 ID 切换线路。导入链接含 Key，不要分享。完整入口见 Orbis 快速开始。

客户端	模型与线路	自定义配置所需信息
Codex	GPT 6.1 Sol，GPT · HA	地址 `https://api.orbiorbi.com/v1`；OpenAI Responses；模型 `gpt-6.1-sol`
Claude Code	Claude Haiku 5.5，Claude Code · AH	地址 `https://api.orbiorbi.com`；Anthropic Messages；模型 `claude-haiku-5-5`

不能自动导入时：左侧选对应客户端→“添加供应商”→“自定义配置”，按上表填写。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 卡片是你添加的配置，不假定软件自带预设。

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

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

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

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

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

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

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

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

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

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

6. 让客户端读到新列表

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

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

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

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

选第一家，发送：

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

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

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

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

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

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

五、进阶使用与恢复

8. 按任务阶段切换

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

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

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

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

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

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

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

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

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

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

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

11. 出错先恢复直连

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

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

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

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

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

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

参考与图片

操作依据官方聚合手册、官方图文指南。组织参考QCode、Gunzo与XieCoding，旧版事实未照搬。