mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-10-25 17:22:27 +08:00
docs: add aggregation mode guide and update user manuals
- Add the Chinese aggregation guide with the final cover, client screenshots, and request-routing diagram - Update Chinese, English, and Japanese manuals to distinguish model fetching, models.dev metadata completion, and manual entry - Clarify official subscription support, default models, and client restart requirements; add README links - Validate 90 local documentation links, five images, and Git diff formatting
This commit is contained in:
Jason committed
1 parent
4aeaccf125
commit
449c7e78af
13 files changed
+271
-34
No files matched your search
@@ -370,9 +370,10 @@ For detailed guides on every feature, check out the **[User Manual](docs/user-ma
|
||||
### Aggregation Mode
|
||||
|
||||
- **One model list, many providers** — On the Claude Code or Codex page, switch to "Aggregation" and add a few providers; their models all appear in the client's model picker. Each request goes to the provider of the model you pick, with no need to switch in CC Switch
|
||||
- **Add and remove anytime** — Click "Add" or "Remove" on a provider card, then pick one provider as the default; requests that don't name an aggregated model go to it. Official accounts can only be the default provider and can't be added to the aggregation
|
||||
- **Add and remove anytime** — Click "Add" or "Remove" on a provider card, then pick one provider as the default; requests that don't name an aggregated model go to it. Codex's OpenAI Official can only be the default provider; Claude official subscriptions are currently unsupported in Aggregation
|
||||
- **Notes** — Aggregation doesn't provide failover; Claude Code requires version 2.1.243 or later; Codex needs a restart after the aggregated list changes, while Claude Code doesn't. When you switch models within a session, the new model has to rebuild its prompt cache, so the first turn costs a bit more
|
||||
- Much of Aggregation mode's design draws on [opencodex](https://github.com/lidge-jun/opencodex) — thanks to its author and contributors
|
||||
- Documentation: [Aggregation mode manual](docs/user-manual/en/4-proxy/4.6-aggregation.md) · [Illustrated guide (Chinese)](docs/guides/aggregation-mode-guide-zh.md)
|
||||
|
||||
### MCP, Prompts & Skills
|
||||
|
||||
|
||||
+2
-1
@@ -370,9 +370,10 @@ Ausführliche Anleitungen zu allen Funktionen finden Sie im **[Benutzerhandbuch]
|
||||
### Aggregationsmodus
|
||||
|
||||
- **Eine Modellliste, mehrere Anbieter** — Wechseln Sie auf der Seite von Claude Code oder Codex zu „Aggregation“ und fügen Sie einige Anbieter hinzu; ihre Modelle erscheinen dann gemeinsam in der Modellauswahl des Clients. Welches Modell Sie wählen, entscheidet, an welchen Anbieter die Anfrage geht — ohne Umweg über CC Switch
|
||||
- **Jederzeit hinzufügen und entfernen** — Klicken Sie auf der Anbieterkarte auf „Add“ oder „Remove“ und bestimmen Sie einen Anbieter als Standard; er übernimmt alle Anfragen, die kein aggregiertes Modell angeben. Offizielle Konten können nur Standardanbieter sein und nicht in die Aggregation aufgenommen werden
|
||||
- **Jederzeit hinzufügen und entfernen** — Klicken Sie auf der Anbieterkarte auf „Add“ oder „Remove“ und bestimmen Sie einen Anbieter als Standard; er übernimmt alle Anfragen, die kein aggregiertes Modell angeben. OpenAI Official in Codex kann nur Standardanbieter sein; offizielle Claude-Abonnements werden im Aggregationsmodus derzeit nicht unterstützt
|
||||
- **Hinweise** — Aggregation bietet kein Failover; Claude Code wird ab Version 2.1.243 benötigt; Codex muss nach Änderungen an der aggregierten Liste neu gestartet werden, Claude Code nicht. Wechseln Sie innerhalb einer Session das Modell, muss das neue Modell den Prompt-Cache neu aufbauen, sodass die erste Runde etwas mehr kostet
|
||||
- Viele Designideen des Aggregationsmodus stammen von [opencodex](https://github.com/lidge-jun/opencodex) — danke an den Autor und alle Mitwirkenden
|
||||
- Dokumentation: [Handbuch zum Aggregationsmodus (Englisch)](docs/user-manual/en/4-proxy/4.6-aggregation.md) · [Illustrierte Anleitung (Chinesisch)](docs/guides/aggregation-mode-guide-zh.md)
|
||||
|
||||
### MCP, Prompts & Skills
|
||||
|
||||
|
||||
+2
-1
@@ -370,9 +370,10 @@ paru -S cc-switch-bin
|
||||
### 集約モード
|
||||
|
||||
- **1 つのモデル一覧に複数のプロバイダ** — Claude Code または Codex のページで「集約」に切り替えてプロバイダをいくつか追加すると、それぞれのモデルがクライアントのモデル選択画面にまとめて表示されます。選んだモデルに応じてそのプロバイダへリクエストが送られるので、CC Switch に戻って切り替える必要はありません
|
||||
- **いつでも追加・削除** — プロバイダカードの「追加」または「削除」をクリックし、さらに 1 社を既定のプロバイダに選びます。集約モデルを指定していないリクエストはすべて既定のプロバイダに送られます。公式アカウントは既定のプロバイダにだけでき、集約には追加できません
|
||||
- **いつでも追加・削除** — プロバイダカードの「追加」または「削除」をクリックし、さらに 1 社を既定のプロバイダに選びます。集約モデルを指定していないリクエストはすべて既定のプロバイダに送られます。Codex の OpenAI Official は既定のプロバイダ専用です。集約モードは現在 Claude の公式サブスクリプションに対応していません
|
||||
- **注意** — 集約ではフェイルオーバーを行いません。Claude Code は 2.1.243 以降が必要です。Codex は集約の一覧が変わると再起動が必要ですが、Claude Code は不要です。同じセッションの途中でモデルを変えると、新しいモデルでプロンプトキャッシュを作り直すため、最初のターンは費用がやや高くなります
|
||||
- 集約モードの設計の多くは [opencodex](https://github.com/lidge-jun/opencodex) を参考にしています。作者とコントリビューターに感謝します
|
||||
- ドキュメント：[集約モードのマニュアル](docs/user-manual/ja/4-proxy/4.6-aggregation.md) · [図解ガイド（中国語）](docs/guides/aggregation-mode-guide-zh.md)
|
||||
|
||||
### MCP、プロンプト & Skills
|
||||
|
||||
|
||||
+2
-1
@@ -371,9 +371,10 @@ paru -S cc-switch-bin
|
||||
### 聚合模式
|
||||
|
||||
- **一个模型列表，多家供应商** — 在 Claude Code 或 Codex 的页面切到「聚合」，添加几家供应商，它们的模型会同时出现在客户端的模型选择器里；选哪个模型，请求就发给哪一家，不用回到 CC Switch 切换
|
||||
- **随时添加和移除** — 在供应商卡片上点“添加”或“移除”，再选一家作为默认供应商，没有指定聚合模型的请求都交给它；官方账号只能作为默认供应商，不能加入聚合
|
||||
- **随时添加和移除** — 在供应商卡片上点“添加”或“移除”，再选一家作为默认供应商，没有指定聚合模型的请求都交给它；Codex 的 OpenAI Official 只能作为默认供应商；聚合模式暂不支持 Claude 官方订阅
|
||||
- **注意** — 聚合不提供故障转移；Claude Code 需要 2.1.243 或更新版本；Codex 的聚合列表变化后需要重启，Claude Code 不需要。同一会话里换模型后，新模型要重新建立提示词缓存，第一轮费用会高一些
|
||||
- 聚合模式的许多设计参考了 [opencodex](https://github.com/lidge-jun/opencodex)，感谢作者和贡献者
|
||||
- 使用攻略：[聚合模式图文指南](docs/guides/aggregation-mode-guide-zh.md) · [聚合模式手册](docs/user-manual/zh/4-proxy/4.6-aggregation.md)
|
||||
|
||||
### MCP、提示词与 Skills
|
||||
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
# CC Switch 聚合模式使用指南
|
||||
|
||||
|
||||
|
||||
用 Claude Code 或 Codex 写代码时，你可能不只使用一家供应商：有自己常用的模型，也有想试试的新模型；有官方订阅，也有另外购买的 API 或编程套餐。
|
||||
|
||||
过去，想换一家供应商，通常要先回到 CC Switch 主界面或者托盘切换，再返回客户端继续工作。CC Switch 4.0 新增的**聚合模式**，让这件事可以直接在客户端里完成：把多家供应商的模型放进同一个模型列表，在应用内无感切换，选哪个模型，请求就发给对应的供应商。
|
||||
|
||||
目前，聚合模式支持 **Claude Code 和 Codex**。这篇文章就从实际效果开始，带你完成配置，并讲清默认供应商、重启和日常切换的区别。
|
||||
|
||||
## 在 Codex 里直接选择多家模型
|
||||
|
||||
先看开启聚合后的 Codex 桌面版。
|
||||
|
||||
|
||||
|
||||
原有的 GPT 模型与来自其他供应商的 Grok、Kimi、DeepSeek 等模型，出现在了同一个列表中。第三方模型名称后面标有供应商，方便辨认具体来源。截图中选中的是 **Kimi K3（Kimi For Coding）**，接下来的请求就会发给配置的 Kimi For Coding 供应商。
|
||||
|
||||
模型名称与可选范围取决于你自己的配置，截图展示的是一组使用示例。即便两家供应商提供同名模型，你也可以根据条目中的供应商名称，选择想使用的那一条线路。
|
||||
|
||||
你可以在一个会话中先讨论方案，再换一个模型继续实现或检查代码，不必为了更换供应商重新开始一段对话。配置完成之后，日常选模型就在客户端里进行。
|
||||
|
||||
## 聚合模式怎样分发请求
|
||||
|
||||
聚合模式做了两件事：先把各家的模型整理到客户端的模型列表里，再根据你选中的条目，把请求发给对应供应商。
|
||||
|
||||
|
||||
|
||||
例如，你选择 Kimi For Coding 提供的模型，CC Switch 就使用这家供应商的连接配置转发请求；换成 DeepSeek 提供的模型，后续请求就交给 DeepSeek。每次请求按所选条目发送，加入多家供应商不会让它们同时回答同一个问题。
|
||||
|
||||
有时你会看到带 `ccs-` 前缀的模型 ID。这是 CC Switch 用来识别供应商和模型的标记，直接在模型列表里选择即可，不需要手动编写。
|
||||
|
||||
## 在 CC Switch 中完成配置
|
||||
|
||||
下面以 Codex 为例。Claude Code 的入口和操作方式相同，但两个应用的聚合名单需要分别配置。
|
||||
|
||||
|
||||
|
||||
截图顶部显示“聚合生效中”，默认供应商是 OpenAI Official，另外添加了 **6 家供应商、共 13 个模型**。每张卡片旁边也标出了这家供应商配置的模型数量。
|
||||
|
||||
### 第一步 进入聚合页面
|
||||
|
||||
在 CC Switch 左侧选择 **Codex**，然后点击顶部的「聚合」标签。
|
||||
|
||||
**点标签只是切换正在查看的页面，不代表已经开启聚合。** 是否真正生效，要看顶部的模式状态。
|
||||
|
||||
### 第二步 准备供应商和模型列表
|
||||
|
||||
如果还没有供应商，点击右上角「添加供应商」，按所选预设填写连接信息，例如 API 地址和密钥；需要登录或绑定账号的供应商，则完成对应的账号配置。已有供应商可以直接点击卡片上的编辑按钮。
|
||||
|
||||
在「聚合」页添加或编辑时，表单会集中展示连接信息和「模型列表」。最近的版本进一步强化了模型列表获取和模型信息补全，配置多家供应商时，可以省去不少逐个查找、复制和填写的工作。
|
||||
|
||||
**一键获取：从供应商拉取模型列表**
|
||||
|
||||
填好连接信息或完成账号配置后，点击「获取模型列表」，CC Switch 就会向供应商查询可用模型。新版适配了更多供应商的模型接口地址和返回格式，减少了因为接口差异而获取不到列表的情况。
|
||||
|
||||
获取成功后，可以搜索、勾选需要的模型，再点击「添加所选模型」批量加入。这一步决定哪些模型会出现在客户端的选择器里：你可以只留下常用的几个，不必把供应商返回的全部模型都加入聚合。
|
||||
|
||||
**自动补全：选好模型后，补上它的能力信息**
|
||||
|
||||
勾选需要的模型并加入列表后，**CC Switch 会自动从 models.dev 拉取对应模型的资料，补全上下文窗口、思考等级等信息**。以本文的 Codex 配置为例，还会根据可用资料补充文字、图片输入能力。选好模型后，这些信息会自动填入空缺的配置项，省去逐项查资料、手动填写的工作。
|
||||
|
||||
补全会优先参考与当前供应商地址匹配的内置预设，再结合 models.dev 中的供应商和原厂模型资料。**已有的参数会保留，自动补全只填写空缺项**；补全后还会提示信息来源，方便核对。不同供应商部署同一模型时，实际支持的窗口和能力可能不同，因此仍应以当前供应商的支持情况为准。
|
||||
|
||||
**手动添加：用于列表缺失或自定义模型**
|
||||
|
||||
如果供应商没有开放模型列表接口，或列表里暂时没有你需要的模型，可以点击「手动添加」，填写供应商实际支持的模型 ID，再按需填写显示名称和能力参数。它适合补充自动获取未覆盖的条目，例如供应商提供的自定义模型别名。
|
||||
|
||||
这里配置的模型，是之后在客户端里可选的内容。无论自动获取还是手动添加，填写名称和参数都不会改变模型本身的能力。
|
||||
|
||||
列表中的 **★ 表示这家供应商的默认模型**。在 Claude Code 中，它位于列表第一项；这家成为默认供应商后，启动默认和后台任务等默认角色会使用它。Codex 则使用配置中指定的默认模型。
|
||||
|
||||
### 第三步 把供应商加入聚合名单
|
||||
|
||||
在「可添加」区域找到需要的供应商，点击「添加」。添加后，它会进入聚合名单。
|
||||
|
||||
添加供应商配置与加入聚合名单是两件事。只是创建了一张供应商卡片，还需要把它加入当前应用的聚合名单。
|
||||
|
||||
第一次使用，可以先配好常用的两三家，确认模型能够正常调用，再逐步增加。
|
||||
|
||||
### 第四步 选择默认供应商并开启
|
||||
|
||||
点击「切换到聚合模式」，在确认框中选择默认供应商，检查将加入的供应商和模型数量，然后确认。
|
||||
|
||||
进入聚合时，CC Switch 会自动启动所需的本地路由服务。看到顶部显示“聚合生效中”，就表示模式已经开启。接下来按客户端要求重新加载模型列表，再选择模型开始使用。
|
||||
|
||||
## 默认供应商负责什么
|
||||
|
||||
**默认供应商承接没有明确指定聚合供应商的普通模型请求。** 你在客户端明确选中了某家聚合模型后，那次请求就会交给对应供应商处理。
|
||||
|
||||
如果你在 Codex 中使用官方账号，同时也想调用第三方模型，可以像截图一样，将 **OpenAI Official 设为默认供应商**，再添加其他供应商。官方模型和第三方模型就能在同一个选择器中使用。
|
||||
|
||||
Codex 的官方账号只能作为默认供应商，不能作为普通聚合成员加入。
|
||||
|
||||
开启聚合后，想更换默认供应商，可以在目标供应商卡片的「更多」菜单里选择「设为默认」。当前默认供应商不能直接移除，需要先把另一家设为默认。
|
||||
|
||||
## 官方订阅的支持范围与账号风险
|
||||
|
||||
Codex 本身支持自定义模型供应商，官方文档也提供了通过代理使用 OpenAI 认证的配置方式。CC Switch 因此支持将 OpenAI Official 设为默认供应商，让官方模型与第三方模型出现在同一个列表中。不过，支持这种接入方式，不等于可以承诺账号“零风险”，使用时仍需遵守平台规则。[Codex 官方认证说明](https://learn.chatgpt.com/docs/auth#alternative-model-providers)
|
||||
|
||||
Claude 官方订阅的情况不同。Anthropic 对第三方工具使用订阅凭据有明确限制，包括禁止第三方开发者代用户通过 Free、Pro 或 Max 订阅凭据转发请求，以及收集、存储或中介处理 Claude.ai 登录凭据。这与用户在原版 Claude Code 中正常登录自己的订阅是不同的情况。[Claude Code 官方规定](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)
|
||||
|
||||
考虑到许多 CC Switch 用户并不熟悉这些接入方式和规则差异，我们选择采取更保守的支持策略：**聚合模式暂不支持 Claude 官方订阅**。需要使用该订阅时，请回到直连模式，在 Claude Code 中通过官方登录流程使用。这个限制针对官方订阅接入，不代表 Claude Code 的聚合模式不能使用其他已支持的模型供应商。
|
||||
|
||||
## 在 Claude Code 中使用聚合模型
|
||||
|
||||
在 CC Switch 左侧选择 Claude Code，配置好它自己的供应商和聚合名单，然后开启聚合。在 Claude Code 中输入 `/model`，就能看到模型列表。
|
||||
|
||||
|
||||
|
||||
截图中的 Kimi、Grok、Claude 和 GPT 系列模型来自不同供应商。括号里显示供应商名称，右侧还展示模型 ID 和配置的上下文窗口。
|
||||
|
||||
选择所需条目后，就可以继续当前会话。模型的上下文窗口、图片输入和工具能力仍取决于实际模型及上游支持，不能只靠修改显示名称或窗口配置获得。
|
||||
|
||||
Claude Code 需要 **2.1.243 或更新版本**才能显示聚合模型。模型列表修改后可以立即生效，无需重启。CC Switch 改写客户端配置后，如果当前选中的是聚合模型，按提示重新选择一次即可。
|
||||
|
||||
## Codex 需要怎样重启
|
||||
|
||||
Codex 在启动时读取模型列表。因此，进入或退出聚合模式、添加或移除供应商、修改模型列表后，需要重新加载。CC Switch 页面里的黄色提示，就是在提醒客户端还在使用旧列表。
|
||||
|
||||
| 使用方式 | 操作方法 |
|
||||
| --- | --- |
|
||||
| Codex 桌面版 | 彻底退出后重新打开。macOS 按 `⌘Q`，只关窗口不够。 |
|
||||
| Codex CLI | 按 CC Switch 提示重启 Codex 守护进程，再重新打开 Codex。仅重开命令行客户端可能仍使用旧列表。 |
|
||||
| 编辑器插件 | 重开编辑器窗口。 |
|
||||
|
||||
所有终端中的 Codex CLI 共用守护进程，重启会中断相关的运行中任务，操作前先等任务结束。
|
||||
|
||||
**重新加载针对的是配置或模型列表发生变化。** 在已经加载好的模型列表里选择另一个模型，不需要每次重启。
|
||||
|
||||
## 聚合和路由怎么选
|
||||
|
||||
CC Switch 的三种模式，适合不同的使用习惯。
|
||||
|
||||
| 模式 | 请求如何发送 | 适合的需求 |
|
||||
| --- | --- | --- |
|
||||
| 直连 | 客户端直接连接供应商 | 使用一家供应商，按需在 CC Switch 切换。 |
|
||||
| 路由 | 经过 CC Switch 本地转发，可配置故障转移 | 需要接口转换，或者故障后自动换供应商。 |
|
||||
| 聚合 | 经过 CC Switch 本地转发，按所选模型发送给对应供应商 | 希望在客户端里随时选择多家模型。 |
|
||||
|
||||
**聚合模式不做故障转移。** 选中的供应商不可用时，需要手动选择其他可用模型。原有故障转移队列和设置会保留，回到路由模式后可以继续使用。
|
||||
|
||||
聚合也不会自动比较价格、挑选最快的模型。它把选择放到你手里：用哪一个模型、走哪一家供应商，由你在客户端决定。
|
||||
|
||||
## 日常使用的几个细节
|
||||
|
||||
**使用期间保持 CC Switch 运行。** 聚合请求需要经过本地服务转发。正常退出 CC Switch 时会自动恢复直连配置，下次启动再接上；之后按页面提示处理客户端刷新。
|
||||
|
||||
**切换模型后的第一轮，费用可能更高。** 在同一会话里换模型，新模型可能需要重新建立提示词缓存。历史对话越长，重新处理上下文的成本越值得留意，缓存通常不能在不同供应商之间直接共享。
|
||||
|
||||
**模型选中后仍可能受到能力差异影响。** CC Switch 会按配置进行必要的接口转换，但不同模型在图片、推理等级、联网搜索等方面的支持并不完全相同。选择模型时，还要考虑正在进行的任务需要哪些能力。
|
||||
|
||||
**移除供应商后，记得重新选模型。** 如果客户端还保留着已移除供应商的旧聚合选项，请求会报错并提示重新选择，不会自动改发给另一家。切回路由模式后，聚合模型会从列表撤下，聚合名单则会保留。
|
||||
|
||||
配置好聚合后，你可以让常用模型保持默认，把其他模型留在选择器中，需要时再切换。在熟悉的 Claude Code 或 Codex 会话里，就能完成从选模型到继续工作的整个过程。
|
||||
|
||||
## 致敬 opencodex
|
||||
|
||||
CC Switch 的聚合模式大量学习和参考了 [opencodex](https://github.com/lidge-jun/opencodex)：通过供应商前缀区分模型，让多家模型同时出现在客户端的选择器里；让 Codex 在使用第三方模型时也能处理上下文压缩；检测后台服务是否仍在使用旧的模型列表，并提醒用户重启。这些设计都受益于 opencodex 的开源探索。
|
||||
|
||||
感谢作者 [@lidge-jun](https://github.com/lidge-jun) 和贡献者们把这些成果分享出来，让其他开发者能够学习、借鉴，并继续改进用户体验。向他们的工作和开源精神致敬！
|
||||
|
||||
如果你希望在 Codex 或 Claude Code 中接入更多供应商和模型，也非常推荐了解和试用 [opencodex](https://github.com/lidge-jun/opencodex)。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [聚合模式用户手册](../user-manual/zh/4-proxy/4.6-aggregation.md)
|
||||
- [本地路由](../user-manual/zh/4-proxy/4.2-routing.md)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 356 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 197 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 453 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.3 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.6 MiB |
@@ -4,7 +4,7 @@
|
||||
|
||||
Aggregation mode puts the models of several providers into one model list in Claude Code or Codex. Whichever model you pick in the client's `/model`, the request goes to that provider; you don't have to go back to CC Switch to switch providers.
|
||||
|
||||
Aggregation mode only supports **Claude Code** and **Codex**.
|
||||
Aggregation mode only supports **Claude Code** and **Codex**. Configure providers and the aggregation list separately for each app.
|
||||
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ Select Claude Code or Codex in the sidebar → the "Aggregation" tab at the top
|
||||
### Steps
|
||||
|
||||
1. Click the "Aggregation" tab. Clicking the tab is only for viewing and doesn't change any configuration
|
||||
2. Confirm the default provider in the "Default provider" area (see below)
|
||||
2. Configure each provider's model list, add the providers you need to the aggregation list, and confirm the default provider (see below)
|
||||
3. Click "Switch to Aggregation"
|
||||
4. In the confirmation dialog, review the default provider and the models that will appear in `/model`, then click "Switch to Aggregation" to confirm
|
||||
|
||||
@@ -48,18 +48,38 @@ In the "Added" list, click "Remove" on the card. Added providers are written int
|
||||
|
||||
### Set Each Provider's Models
|
||||
|
||||
When editing a provider, the form has a "Models" list:
|
||||
When editing a provider, use the "Models" list. Configuring models and adding a provider to Aggregation are separate steps: after saving the provider, click "Add" in the "Available" list.
|
||||
|
||||
- These models appear in `/model`, and picking one sends requests straight to this provider
|
||||
- The first one (★) is this provider's default model; when this provider is the default, Claude Code startup and background tasks and Codex's default model all use it
|
||||
- A provider with no models configured adds nothing to `/model` after joining Aggregation
|
||||
- Click "Add manually" to add more models
|
||||
#### Fetch the Model List
|
||||
|
||||
Enter the API URL and key, or finish the provider's account setup, then click "Fetch Models". CC Switch queries the provider and handles supported endpoint paths and response formats. Search the results, select the models you need, and click "Add selected" to add them in bulk. You don't need to add every returned model.
|
||||
|
||||
#### Fill Model Information Automatically
|
||||
|
||||
For Codex, selecting models and adding them to the list automatically fetches matching information from models.dev to fill in the context window, reasoning levels, and text/image input capabilities. Built-in presets matching the provider's endpoint take priority; provider-specific or original-vendor information from models.dev fills the remaining gaps.
|
||||
|
||||
Only empty fields are filled; existing parameters are preserved. CC Switch also shows the information source for review. Providers may deploy the same model with different capabilities, so check what your provider actually supports. Unmatched information can be entered manually.
|
||||
|
||||
#### Add Models Manually
|
||||
|
||||
Use "Add manually" if the provider has no model-list endpoint, a new model is missing from its list, or you need a custom model alias. Enter a model ID the provider actually supports, then set its display name and capability parameters as needed. Changing a name or context-window setting does not change the model's actual capabilities.
|
||||
|
||||
#### Default Model
|
||||
|
||||
- Configured models appear in the client's model picker; choosing one sends requests to its provider
|
||||
- ★ marks the provider's default model. In Claude Code, it is the first entry and serves startup and background tasks when that provider is the default; Codex uses the default model specified in its configuration
|
||||
- A Claude Code provider with neither a model list nor model mappings adds no selectable models; Codex can also use its configured default model
|
||||
- See "When a Restart Is Needed" below after changing the model list
|
||||
|
||||
## Default Provider
|
||||
|
||||
The default provider takes all requests without a prefix. Click "Set as default" on a provider card to change it.
|
||||
|
||||
If you use an official subscription (a Claude official account, or Codex's OpenAI Official), set the official account as the default provider.
|
||||
For a Codex official account, set **OpenAI Official as the default provider**, then add other providers. OpenAI Official can only be the default provider, not a regular aggregation member.
|
||||
|
||||
**Aggregation currently does not support Claude official subscriptions.** To use one, return to Direct mode and sign in through Claude Code's official login flow. This restriction concerns official subscriptions; Claude Code can still aggregate other supported model providers.
|
||||
|
||||
Supporting an official account does not guarantee zero account risk; platform rules still apply. See the official documentation on [Codex authentication](https://learn.chatgpt.com/docs/auth#alternative-model-providers) and [Claude Code authentication and credential use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use).
|
||||
|
||||
## The `ccs-` Prefix in `/model`
|
||||
|
||||
@@ -82,12 +102,13 @@ Codex only reads its model list at startup. After entering or leaving Aggregatio
|
||||
- **Desktop app**: quit completely and reopen. On macOS press ⌘Q; just closing the window isn't enough
|
||||
- **Editor extension**: reopen the editor window
|
||||
|
||||
Also, after CC Switch rewrites the client config, if the model currently selected in `/model` is an aggregated one, you need to select it again.
|
||||
Choosing another model from an already loaded list does not require a restart each time. In Claude Code, after CC Switch rewrites the client config, reselect the aggregated model if prompted.
|
||||
|
||||
## Limits
|
||||
|
||||
- **No failover**: the queue and settings are kept in Aggregation mode and take effect again once you return to Routing mode
|
||||
- **Official accounts can only be the default provider** and can't join Aggregation
|
||||
- **Codex's OpenAI Official can only be the default provider**, not a regular aggregation member
|
||||
- **Claude official subscriptions are currently unsupported** in Aggregation; use Direct mode for them
|
||||
- **The default provider can't be removed**
|
||||
- **CC Switch must keep running**: quitting CC Switch automatically returns to direct, and it reconnects on the next start
|
||||
- When you return to Routing mode, the aggregated models are withdrawn from `/model` (the list is kept), and an aggregated model that is currently selected needs to be changed back to a regular one
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
集約モードは、複数のプロバイダーのモデルを Claude Code または Codex の同じモデル一覧にまとめます。クライアントの `/model` で選んだモデルに応じてリクエストが該当のプロバイダーに送られるため、CC Switch に戻ってプロバイダーを切り替える必要がありません。
|
||||
|
||||
集約モードは **Claude Code** と **Codex** のみに対応しています。
|
||||
集約モードは **Claude Code** と **Codex** のみに対応しています。プロバイダーと集約リストはアプリごとに設定してください。
|
||||
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@
|
||||
### 操作手順
|
||||
|
||||
1. 「集約」タブをクリックします。タブをクリックしても表示が切り替わるだけで、設定は変わりません
|
||||
2. 「既定のプロバイダー」エリアで既定のプロバイダーを確認します（後述）
|
||||
2. 各プロバイダーのモデル一覧を設定し、必要なプロバイダーを集約リストに追加して、既定のプロバイダーを確認します（後述）
|
||||
3. 「集約に切り替え」をクリックします
|
||||
4. 表示される確認ダイアログで、既定のプロバイダーと `/model` に表示されるモデルを確認し、「集約に切り替え」で確定します
|
||||
|
||||
@@ -48,18 +48,38 @@
|
||||
|
||||
### 各プロバイダーのモデルを設定する
|
||||
|
||||
プロバイダーを編集するときに、フォームに「モデル一覧」があります：
|
||||
プロバイダーの編集フォームにある「モデル一覧」で設定します。モデルの設定と集約への追加は別の操作です。保存後に「追加できるもの」リストで「追加」をクリックしてください。
|
||||
|
||||
- これらのモデルが `/model` に表示され、選ぶとリクエストがそのプロバイダーに直接送られます
|
||||
- 先頭（★）がそのプロバイダーの既定モデルです。そのプロバイダーが既定に設定されている場合、Claude Code の起動時とバックグラウンドタスク、Codex の既定モデルにこれが使われます
|
||||
- モデルを設定していないプロバイダーは、集約に追加しても `/model` にモデルが増えません
|
||||
- 「手動で追加」でモデルを補えます
|
||||
#### モデル一覧を取得する
|
||||
|
||||
API の URL とキーを入力するか、アカウント設定を完了してから「モデル一覧を取得」をクリックします。CC Switch がプロバイダーに問い合わせ、対応するエンドポイントとレスポンス形式を処理します。取得後は検索して必要なモデルにチェックを入れ、「選択したモデルを追加」でまとめて追加できます。返されたモデルをすべて追加する必要はありません。
|
||||
|
||||
#### モデル情報を自動補完する
|
||||
|
||||
Codex では、モデルを選んで一覧に追加すると、models.dev から対応する情報を取得し、コンテキストウィンドウ、思考レベル、テキスト／画像の入力対応を補完します。プロバイダーの接続先に一致する組み込みプリセットが優先され、残りの空欄を models.dev のプロバイダー別情報やモデル開発元の情報で補います。
|
||||
|
||||
既存の値は保持し、空欄だけを補完します。情報源も表示されるので確認してください。同じモデルでもプロバイダーによって対応機能が異なる場合があるため、実際の提供内容を優先してください。一致する情報がない項目は手動で入力できます。
|
||||
|
||||
#### モデルを手動で追加する
|
||||
|
||||
プロバイダーにモデル一覧の API がない場合、新しいモデルが一覧にない場合、独自のモデル別名を使う場合は「手動で追加」を使います。実際に対応しているモデル ID を入力し、必要に応じて表示名や能力の設定を補ってください。名前やコンテキストウィンドウの設定を変えても、モデル自体の能力は変わりません。
|
||||
|
||||
#### 既定のモデル
|
||||
|
||||
- 設定したモデルがクライアントのモデル選択に表示され、選ぶと対応するプロバイダーにリクエストが送られます
|
||||
- ★ はそのプロバイダーの既定モデルです。Claude Code では一覧の先頭にあり、そのプロバイダーが既定の場合に起動時とバックグラウンドタスクで使われます。Codex は設定で指定した既定モデルを使います
|
||||
- Claude Code でモデル一覧もモデルマッピングも設定していないプロバイダーは、選択肢を追加しません。Codex は設定済みの既定モデルも利用できます
|
||||
- 一覧を変更した後の反映方法は、下の「再起動が必要なとき」を参照してください
|
||||
|
||||
## 既定のプロバイダー
|
||||
|
||||
既定のプロバイダーは、プレフィックスのないすべてのリクエストを受けます。プロバイダーカードの「既定にする」で変更できます。
|
||||
|
||||
公式サブスクリプション（Claude 公式アカウント、Codex の OpenAI Official）を使っている場合は、公式アカウントを既定のプロバイダーにしてください。
|
||||
Codex の公式アカウントを使う場合は、**OpenAI Official を既定のプロバイダーに設定**してから、ほかのプロバイダーを追加します。OpenAI Official は既定のプロバイダー専用で、通常の集約メンバーには追加できません。
|
||||
|
||||
**集約モードは現在、Claude の公式サブスクリプションに対応していません。** 利用する場合は直接接続に戻し、Claude Code の公式ログイン手順でサインインしてください。この制限は公式サブスクリプションに関するもので、Claude Code でほかの対応プロバイダーを集約することは可能です。
|
||||
|
||||
公式アカウントに対応していることは、アカウントのリスクがゼロであるという保証ではありません。各プラットフォームの規則に従ってください。公式情報：[Codex の認証](https://learn.chatgpt.com/docs/auth#alternative-model-providers)、[Claude Code の認証と認証情報の利用](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)。
|
||||
|
||||
## `/model` の `ccs-` プレフィックス
|
||||
|
||||
@@ -82,12 +102,13 @@ Codex はモデル一覧を起動時にしか読み込みません。集約に
|
||||
- **デスクトップ版**：完全に終了してから開き直します。macOS では ⌘Q を押します。ウィンドウを閉じるだけでは不十分です
|
||||
- **エディター拡張**：エディターのウィンドウを開き直します
|
||||
|
||||
また、CC Switch がクライアント設定を書き換えるたびに、`/model` で集約したモデルを選択している場合は、もう一度選び直す必要があります。
|
||||
読み込み済みの一覧から別のモデルを選ぶだけなら、その都度再起動する必要はありません。Claude Code では、CC Switch がクライアント設定を書き換えた後、集約モデルを選択中の場合は案内に従って選び直してください。
|
||||
|
||||
## 制限事項
|
||||
|
||||
- **フェイルオーバーはしません**：集約モードの間もキューと設定は保持され、ルーティングモードに戻すと復元されます
|
||||
- **公式アカウントは既定のプロバイダーにしかできず**、集約には追加できません
|
||||
- **Codex の OpenAI Official は既定のプロバイダー専用**で、通常の集約メンバーには追加できません
|
||||
- **Claude の公式サブスクリプションには現在非対応**です。直接接続で利用してください
|
||||
- **既定のプロバイダーは削除できません**
|
||||
- **CC Switch を起動し続ける必要があります**：CC Switch を終了すると自動的に直接接続に戻り、次回の起動時に再び接続されます
|
||||
- ルーティングモードに戻すと、集約したモデルは `/model` から外れます（リストは保持）。選択中の集約したモデルは通常のモデルに戻す必要があります
|
||||
|
||||
@@ -4,7 +4,9 @@
|
||||
|
||||
聚合模式把多家供应商的模型放进 Claude Code 或 Codex 的同一个模型列表。在客户端的 `/model` 里选哪个模型，请求就发给哪一家，不用回到 CC Switch 切换供应商。
|
||||
|
||||
聚合模式只支持 **Claude Code** 和 **Codex**。
|
||||
聚合模式只支持 **Claude Code** 和 **Codex**，两个应用的供应商和聚合名单需要分别配置。
|
||||
|
||||
完整图文步骤见 [聚合模式使用攻略](../../../guides/aggregation-mode-guide-zh.md)。
|
||||
|
||||
|
||||
|
||||
@@ -28,7 +30,7 @@
|
||||
### 操作步骤
|
||||
|
||||
1. 点「聚合」标签。点标签只是查看，不会改动配置
|
||||
2. 在「默认供应商」区域确认默认供应商（见下文）
|
||||
2. 配好各家的模型列表，把需要的供应商加入聚合名单，再确认默认供应商（见下文）
|
||||
3. 点“切换到聚合模式”
|
||||
4. 在弹出的确认框里查看默认供应商和将出现在 `/model` 里的模型，点“切换到聚合模式”确认
|
||||
|
||||
@@ -48,18 +50,38 @@
|
||||
|
||||
### 设置每家的模型
|
||||
|
||||
编辑供应商时，表单里有「模型列表」：
|
||||
编辑供应商时，表单里有「模型列表」。配置模型列表和把供应商加入聚合名单是两个步骤：保存供应商后，还要在「可添加」区域点“添加”。
|
||||
|
||||
- 这些模型会出现在 `/model` 里，选中后请求直达这家
|
||||
- 第一个（★）是这家的默认模型；这家被设为默认时，Claude Code 启动和后台任务、Codex 的默认模型都用它
|
||||
- 没有配置模型的供应商，加入聚合后不会在 `/model` 里多出任何模型
|
||||
- 可以点“手动添加”补充模型
|
||||
#### 获取模型列表
|
||||
|
||||
填好 API 地址、密钥或完成对应账号配置后，点击“获取模型列表”。CC Switch 会向供应商查询模型，并适配已支持的接口地址和返回格式。获取成功后，搜索并勾选需要的模型，点击“添加所选模型”批量加入；无需把返回的全部模型都加入。
|
||||
|
||||
#### 自动补全模型信息
|
||||
|
||||
以 Codex 为例，勾选模型并加入列表后，CC Switch 会自动从 models.dev 获取模型资料，补全可匹配到的上下文窗口、思考等级和文字／图片输入能力。匹配当前供应商地址的内置预设优先，其余空缺再由 models.dev 的供应商或原厂资料补充。
|
||||
|
||||
自动补全只填写空缺项，保留已有参数，并提示信息来源供核对。不同供应商部署的同名模型可能有不同能力，请以当前供应商实际支持的参数为准；无法匹配到的信息可以手动填写。
|
||||
|
||||
#### 手动添加模型
|
||||
|
||||
供应商未开放模型列表接口、列表暂未包含新模型，或需要填写自定义模型别名时，可以点击“手动添加”，填写供应商实际支持的模型 ID，再按需填写显示名称和能力参数。修改名称、上下文窗口等配置不会改变模型本身的能力。
|
||||
|
||||
#### 默认模型
|
||||
|
||||
- 配置的模型会出现在客户端的模型选择器里，选中后请求发给对应供应商
|
||||
- ★ 表示这家供应商的默认模型。Claude Code 中它位于列表第一项，供默认供应商的启动和后台任务使用；Codex 使用配置中指定的默认模型
|
||||
- Claude Code 供应商既未配置模型列表，也未配置模型映射时，加入聚合后不会新增可选模型；Codex 还可使用其已配置的默认模型
|
||||
- 模型列表修改后的客户端刷新方式见下文“什么时候需要重启”
|
||||
|
||||
## 默认供应商
|
||||
|
||||
默认供应商承接所有不带前缀的请求。在供应商卡片上点“设为默认”可以更换。
|
||||
|
||||
如果你在用官方订阅（Claude 官方账号、Codex 的 OpenAI Official），请把官方账号设为默认供应商。
|
||||
使用 Codex 官方账号时，可以将 **OpenAI Official 设为默认供应商**，再添加其他供应商。OpenAI Official 只能作为默认供应商，不能作为普通聚合成员加入。
|
||||
|
||||
**聚合模式暂不支持 Claude 官方订阅**。需要使用该订阅时，请回到直连模式，在 Claude Code 中通过官方登录流程使用。这个限制针对 Claude 官方订阅，不影响 Claude Code 聚合其他已支持的模型供应商。
|
||||
|
||||
支持官方账号接入不等于承诺账号“零风险”，使用时仍需遵守平台规则。官方说明：[Codex 认证](https://learn.chatgpt.com/docs/auth#alternative-model-providers)、[Claude Code 认证与凭据使用](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)。
|
||||
|
||||
## `/model` 里的 `ccs-` 前缀
|
||||
|
||||
@@ -82,12 +104,13 @@ Codex 只在启动时读取模型列表。进入或退出聚合、添加或移
|
||||
- **桌面版**：彻底退出再重开。macOS 上按 ⌘Q，只关窗口不行
|
||||
- **编辑器插件**：重开编辑器窗口
|
||||
|
||||
另外，CC Switch 每次改写客户端配置后，如果 `/model` 里当前选的是聚合的模型，需要重新选一次。
|
||||
在已经加载好的模型列表里选择另一个模型，不需要每次重启。Claude Code 在 CC Switch 改写客户端配置后，如果当前选中的是聚合模型，请按提示重新选择一次。
|
||||
|
||||
## 限制
|
||||
|
||||
- **不做故障转移**：聚合模式下队列和设置会保留，回到路由模式后恢复
|
||||
- **官方账号只能作默认供应商**，不能加入聚合
|
||||
- **Codex 的 OpenAI Official 只能作默认供应商**，不能作为普通聚合成员加入
|
||||
- **暂不支持 Claude 官方订阅**，需要回到直连模式使用
|
||||
- **默认供应商不能移除**
|
||||
- **需要 CC Switch 保持运行**：退出 CC Switch 会自动回到直连，下次启动再接上
|
||||
- 回到路由模式时，聚合的模型会从 `/model` 撤下（名单保留），已选中的聚合模型需要改回普通模型
|
||||
|
||||
Reference in new issue
Block a user