admin/CC-Switch
1
0
Fork 0
mirror of https://github.com/farion1231/cc-switch.git synced 2026-07-29 09:37:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: document Codex Chat provider support in changelog and manual

Browse Source 
Backfill the empty [Unreleased] CHANGELOG section with the Codex Chat
Completions feature (Chat-to-Responses bridge, 23 third-party presets,
model mapping table, Stream Check routing, error-envelope conversion,
"custom" history bucket) plus the community fixes landed since v3.15.0.

Update the zh/en/ja user manual: split the Codex preset tables by
upstream protocol (native Responses vs Chat Completions), add a "Codex
Local Routing and Model Mapping" section covering the Needs Local
Routing toggle and the model catalog, and note Chat-format probing in
the Stream Check guide. Manual wording matches the live UI strings.
This commit is contained in:
Jason
2026-05-21 09:42:44 +08:00
parent ead9e22b21
commit 04af87bc7b
7 changed files with 214 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/user-manual/en/2-providers/2.1-add.md
+57 -4
View File
@@ -68,6 +68,10 @@ See [2.6 Claude Desktop](./2.6-claude-desktop.md) for the full workflow.
#### Codex Presets
Codex presets fall into two groups by upstream protocol.
**Native Responses protocol** (direct connection or standard proxy forwarding):
| Preset Name | Description |
|-------------|-------------|
| OpenAI Official | Log in with an OpenAI official account |
@@ -75,11 +79,32 @@ See [2.6 Claude Desktop](./2.6-claude-desktop.md) for the full workflow.
| AiHubMix | AiHubMix aggregation service |
| DMXAPI | DMXAPI proxy service |
| PackyCode | PackyCode proxy service |
| Cubence | Cubence service |
| AIGoCode | AIGoCode service |
| RightCode | RightCode service |
| AICodeMirror | AICodeMirror service |
| OpenRouter | Aggregation routing service |
| Cubence / AIGoCode / RightCode / AICodeMirror, etc. | Various proxy services |
**Chat Completions protocol** (requires the **Needs Local Routing** toggle; converted automatically by the proxy):
| Preset Name | Description |
|-------------|-------------|
| DeepSeek | DeepSeek models |
| Zhipu GLM / GLM en | Zhipu AI GLM models |
| Kimi / Kimi For Coding | Moonshot Kimi models |
| MiniMax / MiniMax en | MiniMax models |
| StepFun / StepFun en | StepFun Step models |
| Baidu Qianfan Coding Plan | Baidu Qianfan coding plan |
| Bailian | Alibaba Cloud Bailian (Qwen) |
| ModelScope | ModelScope community |
| Longcat | Longcat AI |
| BaiLing | BaiLing AI |
| Xiaomi MiMo / MiMo Token Plan | Xiaomi MiMo models |
| Volcengine Agentplan | Volcengine Agent Plan |
| BytePlus | BytePlus service |
| DouBaoSeed | DouBao Seed models |
| SiliconFlow / SiliconFlow en | SiliconFlow |
| Novita AI | Novita AI service |
| Nvidia | Nvidia AI service |
> 💡 When you pick a Chat Completions preset, the **Needs Local Routing** toggle and the model mapping table are configured automatically; see the "Codex Local Routing and Model Mapping" section below. The preset list is updated continuously — refer to the in-app list for the authoritative version.
#### Gemini Presets
@@ -528,6 +553,34 @@ When a toggle is unchecked, its corresponding config entry is removed entirely.
Additionally, the **Write Common Config** checkbox enables merging a global config snippet into the provider. Click **Edit Common Config** to customize the shared snippet.
### Codex Local Routing and Model Mapping
Some third-party providers only support the **OpenAI Chat Completions** protocol or use non-GPT model names (such as DeepSeek, Kimi, or MiniMax). Codex natively understands only the OpenAI Responses API and GPT-series models, so these providers need CC Switch to convert the protocol and models locally.
#### Needs Local Routing
When editing a Codex provider, a **Needs Local Routing** toggle is available:
- **When to enable**: the provider uses the Chat Completions protocol, or its model names are not Codex's default GPT series
- **When enabled**: CC Switch's local proxy converts the Responses requests Codex sends into upstream Chat Completions, then converts the response (including streaming SSE, reasoning content, and tool calls) back into Responses format
- **Prerequisite**: [local routing](../4-proxy/4.1-service.md) must be running with Codex takeover enabled for conversion to take effect; keep local routing running while in use
> 💡 When you pick a Chat-format preset such as DeepSeek or Kimi, this toggle is enabled by default — no manual setup needed.
#### Model Mapping
Once **Needs Local Routing** is enabled, a **Model Mapping** table appears below it to declare the models available for this provider:
| Field | Description |
|-------|-------------|
| Model ID | The real upstream model name, e.g. `deepseek-v4-flash` |
| Display Name | (Optional) The name shown in the `/model` command |
| Context Window | (Optional) The model's context length |
- The mapping table generates Codex's `model_catalog_json` so the `/model` command lists these third-party model names
- Entries are saved exactly as listed and are the single source of truth for the model list
- **Codex must be restarted** to refresh the model list after changes (`model_catalog_json` is loaded at Codex startup)
### Codex 1M Context Window
When adding a Codex provider, an **Enable 1M Context Window** toggle is available:
docs/user-manual/en/4-proxy/4.5-model-test.md
+2
View File
@@ -12,6 +12,8 @@ The model test feature (also known as **Stream Check**) verifies whether a provi
Starting from v3.13.0, Stream Check coverage is extended to **Claude / Codex / Gemini / OpenCode / OpenClaw**, including all OpenClaw protocol variants (such as `openai-completions`). OpenCode is auto-detected via npm package mapping; OpenClaw supports custom `auth-header` detection and handles edge cases like Bedrock error messages and `baseURL` fallback.
For Codex third-party providers that use the Chat Completions protocol (such as DeepSeek, Kimi, or MiniMax), Stream Check probes the `/chat/completions` endpoint (instead of `/responses`) and aligns its URL fallback order with the actual proxy forwarding path (origin-only addresses try `/v1/...` first), so a working provider is not mistakenly flagged as unavailable.
## Open Configuration
Settings > Advanced > Model Test Config
docs/user-manual/ja/2-providers/2.1-add.md
+57 -4
View File
@@ -68,6 +68,10 @@ Claude Desktop パネルには、Claude Code のプリセットカタログか
#### Codex プリセット
Codex プリセットは上流プロトコルにより 2 種類に分かれます。
**ネイティブ Responses プロトコル**（直接接続または標準プロキシ転送）：
| プリセット名 | 説明 |
|----------|------|
| OpenAI 公式 | OpenAI 公式アカウントでログイン |
@@ -75,11 +79,32 @@ Claude Desktop パネルには、Claude Code のプリセットカタログか
| AiHubMix | AiHubMix 統合サービス |
| DMXAPI | DMXAPI 中継サービス |
| PackyCode | PackyCode 中継サービス |
| Cubence | Cubence サービス |
| AIGoCode | AIGoCode サービス |
| RightCode | RightCode サービス |
| AICodeMirror | AICodeMirror サービス |
| OpenRouter | 統合ルーティングサービス |
| Cubence / AIGoCode / RightCode / AICodeMirror など | 各種中継サービス |
**Chat Completions プロトコル**（「ローカルルーティングが必要」トグルが必要。プロキシが自動変換）：
| プリセット名 | 説明 |
|----------|------|
| DeepSeek | DeepSeek モデル |
| Zhipu GLM / GLM en | Zhipu AI の GLM モデル |
| Kimi / Kimi For Coding | Moonshot Kimi モデル |
| MiniMax / MiniMax en | MiniMax モデル |
| StepFun / StepFun en | StepFun Step モデル |
| Baidu Qianfan Coding Plan | 百度千帆コーディングプラン |
| Bailian | Alibaba Cloud 百錬（Qwen） |
| ModelScope | ModelScope コミュニティ |
| Longcat | Longcat AI |
| BaiLing | BaiLing AI |
| Xiaomi MiMo / MiMo Token Plan | Xiaomi MiMo モデル |
| Volcengine Agentplan | Volcengine Agent Plan |
| BytePlus | BytePlus サービス |
| DouBaoSeed | DouBao Seed モデル |
| SiliconFlow / SiliconFlow en | SiliconFlow |
| Novita AI | Novita AI サービス |
| Nvidia | Nvidia AI サービス |
> 💡 Chat Completions 系プリセットを選択すると、「ローカルルーティングが必要」トグルとモデルマッピング表が自動的に設定されます。詳細は下記の「Codex ローカルルーティングとモデルマッピング」セクションを参照してください。プリセット一覧は継続的に更新されます。アプリ内の表示を正としてください。
#### Gemini プリセット
@@ -528,6 +553,34 @@ Claude プロバイダーの編集時、JSON エディタの上部に **クイ
また、**共通設定を書き込み** チェックボックスを有効にすると、グローバル設定スニペットをプロバイダーにマージできます。**共通設定を編集** をクリックして共有スニペットをカスタマイズできます。
### Codex ローカルルーティングとモデルマッピング
一部の第三者プロバイダーは **OpenAI Chat Completions** プロトコルのみをサポートするか、非 GPT モデル名（DeepSeek、Kimi、MiniMax など）を使用します。Codex はネイティブには OpenAI Responses API と GPT 系列モデルのみを認識するため、これらのプロバイダーでは CC Switch がローカルでプロトコルとモデルを変換する必要があります。
#### ローカルルーティングが必要
Codex プロバイダーの編集時、**ローカルルーティングが必要** トグルが利用できます：
- **有効にするタイミング**：プロバイダーが Chat Completions プロトコルを使用する、またはモデル名が Codex デフォルトの GPT 系列でない場合
- **有効時**：CC Switch のローカルプロキシが、Codex の送信する Responses リクエストを上流の Chat Completions に変換し、レスポンス（ストリーミング SSE、推論内容、ツール呼び出しを含む）を Responses 形式に再変換します
- **前提条件**：変換を有効にするには[ローカルルーティング](../4-proxy/4.1-service.md)を起動し、Codex の引き継ぎを有効にする必要があります。使用中はローカルルーティングを起動したままにしてください
> 💡 DeepSeek や Kimi などの Chat 形式プリセットを選択すると、このトグルはデフォルトで有効になっており、手動設定は不要です。
#### モデルマッピング
**ローカルルーティングが必要** を有効にすると、その下に **モデルマッピング** 表が表示され、このプロバイダーで利用可能なモデルを宣言できます：
| フィールド | 説明 |
|------|------|
| モデル ID | 上流の実際のモデル名（例：`deepseek-v4-flash`） |
| 表示名 | （任意）`/model` コマンドに表示される名称 |
| コンテキストウィンドウ | （任意）モデルのコンテキスト長 |
- マッピング表は Codex の `model_catalog_json` を生成し、`/model` コマンドでこれらの第三者モデル名を表示できるようにします
- リストの内容はそのまま保存され、モデルリストの唯一の情報源となります
- 変更後、モデルリストを更新するには **Codex の再起動が必要** です（`model_catalog_json` は Codex 起動時に読み込まれます）
### Codex 1M コンテキストウィンドウ
Codex プロバイダーの追加時、**1M コンテキストウィンドウを有効化** トグルが利用できます：
docs/user-manual/ja/4-proxy/4.5-model-test.md
+2
View File
@@ -12,6 +12,8 @@
v3.13.0 より、Stream Check の対応範囲が **Claude / Codex / Gemini / OpenCode / OpenClaw** に拡張され、OpenClaw の全プロトコルバリアント（`openai-completions` など）も含まれます。OpenCode は npm パッケージマッピングで自動識別、OpenClaw はカスタム `auth-header` 検出、Bedrock エラーメッセージ、`baseURL` フォールバックなどのエッジケースにも対応しています。
Chat Completions プロトコルを使用する Codex 第三者プロバイダー（DeepSeek、Kimi、MiniMax など）の場合、Stream Check は `/responses` ではなく `/chat/completions` エンドポイントをプローブし、実際のプロキシ転送パスと URL フォールバック順序を一致させます（origin-only アドレスは `/v1/...` を優先）。これにより、使用可能なプロバイダーが誤って利用不可と判定されることを防ぎます。
## 設定を開く
設定 → 詳細 → モデルテスト
docs/user-manual/zh/2-providers/2.1-add.md
+57 -4
View File
@@ -68,6 +68,10 @@ Claude Desktop 面板内置从 Claude Code 预设目录转换而来的供应商
#### Codex 预设
Codex 预设按上游协议分两类。
**原生 Responses 协议**（可直连或经标准代理转发）：
| 预设名称 | 说明 |
|----------|------|
| OpenAI 官方 | 使用 OpenAI 官方账号登录 |
@@ -75,11 +79,32 @@ Claude Desktop 面板内置从 Claude Code 预设目录转换而来的供应商
| AiHubMix | AiHubMix 聚合服务 |
| DMXAPI | DMXAPI 中转服务 |
| PackyCode | PackyCode 中转服务 |
| Cubence | Cubence 服务 |
| AIGoCode | AIGoCode 服务 |
| RightCode | RightCode 服务 |
| AICodeMirror | AICodeMirror 服务 |
| OpenRouter | 聚合路由服务 |
| Cubence / AIGoCode / RightCode / AICodeMirror 等 | 各类中转服务 |
**Chat Completions 协议**（需开启「需要本地路由映射」，由代理自动转换）：
| 预设名称 | 说明 |
|----------|------|
| DeepSeek | DeepSeek 模型 |
| 智谱 GLM / GLM en | 智谱 AI 的 GLM 模型 |
| Kimi / Kimi For Coding | Moonshot Kimi 模型 |
| MiniMax / MiniMax en | MiniMax 模型 |
| StepFun / StepFun en | 阶跃星辰 Step 模型 |
| 百度千帆 Coding Plan | 百度千帆编程套餐 |
| 百炼 | 阿里云百炼（通义千问） |
| ModelScope | 魔搭社区 |
| Longcat | Longcat AI |
| 百灵 (BaiLing) | 百灵 AI |
| 小米 MiMo / MiMo Token Plan | 小米 MiMo 模型 |
| 火山 Agentplan | 火山引擎 Agent Plan |
| BytePlus | BytePlus 服务 |
| DouBaoSeed | 豆包 Seed 模型 |
| SiliconFlow / SiliconFlow en | 硅基流动 |
| Novita AI | Novita AI 服务 |
| Nvidia | Nvidia AI 服务 |
> 💡 选择 Chat Completions 类预设时，「需要本地路由映射」开关和模型映射表会自动配置好，无需手动设置；详见下文「Codex 本地路由与模型映射」一节。预设列表持续更新，以应用内实际显示为准。
#### Gemini 预设
@@ -528,6 +553,34 @@ v3.13.0 起新增的高级选项。默认情况下，CC Switch 会把配置的 `
此外，**写入通用配置** 复选框可将全局配置片段合并到供应商中。点击 **编辑通用配置** 可自定义共享的配置片段。
### Codex 本地路由与模型映射
部分第三方供应商只支持 **OpenAI Chat Completions** 协议，或使用非 GPT 模型名（如 DeepSeek、Kimi、MiniMax）。Codex 原生只认 OpenAI Responses API 与 GPT 系列模型，因此这类供应商需要 CC Switch 在本地做协议与模型转换。
#### 需要本地路由映射
编辑 Codex 供应商时，提供 **需要本地路由映射** 开关：
- **何时打开**：供应商使用 Chat Completions 协议，或模型名不是 Codex 默认的 GPT 系列
- **打开后**：CC Switch 本地代理会把 Codex 发出的 Responses 请求转换为上游的 Chat Completions，再把响应（含流式 SSE、推理内容、工具调用）转换回 Responses 格式
- **前提条件**：必须开启[本地路由服务](../4-proxy/4.1-service.md)并启用 Codex 接管，转换才会生效；使用过程中需保持本地路由开启
> 💡 选择 DeepSeek、Kimi 等 Chat 格式预设时，此开关默认已打开，无需手动设置。
#### 模型映射
「需要本地路由映射」开启后，下方会出现 **模型映射** 表，用于声明该供应商可用的模型：
| 字段 | 说明 |
|------|------|
| 模型 ID | 上游真实模型名，如 `deepseek-v4-flash` |
| 显示名称 | （可选）在 `/model` 命令中显示的名称 |
| 上下文窗口 | （可选）模型的上下文长度 |
- 映射表会生成 Codex 的 `model_catalog_json`，让 Codex 的 `/model` 命令列出这些第三方模型名
- 表中条目按填写内容原样保存，是模型列表的唯一来源
- **修改后需要重启 Codex** 才能刷新模型列表（`model_catalog_json` 在 Codex 启动时加载）
### Codex 1M 上下文窗口
添加 Codex 供应商时，提供 **启用 1M 上下文窗口** 开关：
docs/user-manual/zh/4-proxy/4.5-model-test.md
+2
View File
@@ -12,6 +12,8 @@
v3.13.0 起，Stream Check 覆盖范围扩展到 **Claude / Codex / Gemini / OpenCode / OpenClaw**，包括 OpenClaw 的全部协议变体（`openai-completions` 等）。OpenCode 通过 npm 包映射自动识别；OpenClaw 支持自定义 `auth-header` 检测，并处理了 Bedrock 错误消息、`baseURL` 回退等边界情况。
对于使用 Chat Completions 协议的 Codex 第三方供应商（如 DeepSeek、Kimi、MiniMax），Stream Check 会探测 `/chat/completions` 端点（而非 `/responses`），并与代理实际转发的 URL 顺序保持一致（origin-only 地址优先尝试 `/v1/...`），避免把可用供应商误判为不可用。
## 打开配置
设置 → 高级 → 模型测试