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

docs(guides): update Codex DeepSeek routing guide for v3.19.1

Browse Source 
The guide used DeepSeek as its Chat-format example, which stopped being
accurate once the preset moved to native Responses. It is not obsolete,
though: a provider saved before 3.19.1 keeps its stored apiFormat and
still carries the "needs routing" badge, and deepseek-v4-pro has no
official Codex integration yet, so Chat + routing remains its only path.

Rather than swap in a different provider, open with a check for which
case the reader is in (badge present/absent/no-routing-support) plus a
three-row table for DeepSeek specifically. The title and filename stay
put — six published release notes and three sibling guides link here.

Also in this pass:

- Drop the screenshot of the old boolean "needs local routing mapping"
  toggle; that control is now Advanced Options -> Upstream Format, a
  three-way select. The image file stays, since the official-auth
  preservation guide still references it.
- Document the Anthropic Messages format, previously unmentioned.
- Fix the Chat-provider list: DeepSeek and MiniMax both moved to
  Responses, so name Kimi, Zhipu GLM, SiliconFlow and ModelScope.
- Note that converting an existing provider keeps the official catalog's
  capabilities (freeform apply_patch, GPT-5 harness, low/high/max,
  web_search) but that its stored contextWindow of 1000000 overrides the
  official 1048576, with two ways to fix it.
- Record the direct connection's prerequisites: Codex CLI 0.144.0+ and a
  ~75 KB catalog file.
- Add a usage-attribution section: the provider dimension collapses into
  Codex (Session), while the model dimension still separates rows.
- Reference DeepSeek's official Codex integration and Responses API docs.

All UI terms are taken from the locale files so they match what the app
actually renders in each language.
This commit is contained in:
Jason
2026-08-01 10:29:32 +08:00
parent 28529620f4
commit a4bba43f73
3 changed files with 181 additions and 64 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guides/codex-deepseek-routing-guide-en.md
+61 -22
View File
@@ -1,15 +1,35 @@
# Using DeepSeek-Style Chat APIs in Codex: CC Switch Local Routing Guide
> Applies to CC Switch 3.16.0 and nearby versions. This guide is based on the repository documentation and code, and uses DeepSeek as an example of an OpenAI Chat Completions-compatible API. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key or account balance.
> Applies to CC Switch 3.19.1 and later. This guide is based on the repository documentation and code. Screenshots are generated with de-identified sample data to avoid exposing a real API key or account balance.
>
> **Important change as of 3.19.1**: the DeepSeek preset now connects directly over native Responses and no longer needs local routing. The routing-conversion path is not obsolete, though — it remains the only way to reach `deepseek-v4-pro`, it still applies to providers saved before the upgrade, and it is how Chat-format providers such as Kimi and Zhipu GLM work. Read the next section first to find out which case you are in.
## First, check whether you still need this guide
There is exactly one way to tell: look for the `Needs Routing` badge on the Codex provider card.
![Needs routing marker in the Codex provider list](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
- **Has the `Needs Routing` badge** → this provider is Chat-format, and the whole guide applies.
- **No badge** → it already connects directly over native Responses, so the routing steps here are pointless for it. Just use it.
- **Has the `No Routing Support` badge** → this is an official provider, and CC Switch blocks it from going through local routing (see the FAQ at the end).
The badge is driven by the API format recorded when the provider was saved, so upgrading CC Switch **does not** change how an existing provider behaves. For DeepSeek specifically, there are three cases after upgrading to 3.19.1:
| Your situation | Routing needed? | Notes |
|---|---|---|
| A DeepSeek provider saved before 3.19.1 | **Yes**, badge still shown | Preset changes only affect newly created providers; a saved configuration is kept as-is. To move it to a direct connection, see the end of Step 1 |
| A DeepSeek provider created from the preset after 3.19.1 | No | Connects directly to `api.deepseek.com` and picks up DeepSeek's official model catalog |
| You want to use `deepseek-v4-pro` | **Yes** | DeepSeek has not opened its Codex integration for that model yet (early August 2026 by their own estimate), so a direct connection fails upstream; it has to go through Chat + routing |
Beyond DeepSeek, plenty of providers are still Chat-format — Kimi, Zhipu GLM, SiliconFlow, ModelScope and others — and this guide applies to them in full. Just substitute the relevant preset wherever DeepSeek appears below.
## Why local routing is needed
The newer Codex CLI targets the OpenAI Responses API, while DeepSeek, Kimi, MiniMax, SiliconFlow, and many other providers expose the OpenAI Chat Completions shape, usually `/chat/completions`. These two protocols use different request bodies, streaming events, and response structures. If you put a Chat endpoint directly into Codex configuration, common results include an incorrect model list, 404/400 requests, or streaming responses that Codex cannot parse correctly.
The newer Codex CLI targets the OpenAI Responses API, while many providers expose the OpenAI Chat Completions shape, usually `/chat/completions`. These two protocols use different request bodies, streaming events, and response structures. If you put a Chat endpoint directly into Codex configuration, common results include an incorrect model list, 404/400 requests, or streaming responses that Codex cannot parse correctly.
CC Switch solves this by making Codex always talk to a local route and continue sending Responses API requests. The route detects whether the active provider is Chat-format, rewrites the request into Chat Completions for the upstream provider, and finally converts the Chat response back into the Responses shape that Codex understands.
![Needs routing marker in the Codex provider list](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
The chain has four main steps:
1. When Codex routing is enabled, the local configuration is written as `http://127.0.0.1:15721/v1`, while `wire_api = "responses"` is kept in place.
@@ -17,56 +37,69 @@ The chain has four main steps:
3. The route rewrites `/responses` or `/v1/responses` to `/chat/completions`, and converts the Responses request body into a Chat request body.
4. After the upstream responds, the route converts the Chat JSON or SSE stream back into Responses JSON/SSE.
For a provider that is natively Responses — such as the current DeepSeek preset — steps 2 through 4 never happen: the request goes straight to the upstream with no format rewriting at all.
## Prerequisites
Prepare these three things first:
- CC Switch installed and able to start.
- Codex CLI installed and run at least once, so the `~/.codex/config.toml` directory structure exists.
- An API key from DeepSeek or another Chat Completions provider.
- An API key for the provider you want to use.
DeepSeek's official documentation currently lists the OpenAI-compatible base URL as `https://api.deepseek.com` (other providers often use a base URL with a `/v1` suffix), and the Chat API path as `/chat/completions`. CC Switch's DeepSeek preset already contains these details, so prefer the preset and do not manually assemble the endpoint path.
Taking DeepSeek as the example, its official documentation lists the OpenAI-compatible base URL as `https://api.deepseek.com` (other providers commonly use a base URL with a `/v1` suffix or a longer path — Zhipu GLM, for instance, uses `https://open.bigmodel.cn/api/coding/paas/v4`), and the Chat API path as `/chat/completions`. CC Switch's presets already carry these details, so prefer a preset and do not manually assemble the endpoint path.
## Step 1: Add a Codex provider
Open CC Switch, switch to the top-level `Codex` tab, and click the plus button in the upper-right corner to add a provider.
Choose the built-in `DeepSeek` preset. You only need to do two things:
**Using a preset** (recommended): select the provider in the preset list, enter your API key, and save. The preset already carries the request base URL, default model, and model menu, and sets the upstream format for you; once a Chat-format preset is saved, the `Needs Routing` badge appears on its card. Thinking/reasoning parameters are preconfigured by the preset — you do not need to fill them in.
- Enter your DeepSeek API key.
- Save the provider.
**Using a custom configuration**: enter the API key and base URL from the provider's documentation, then expand `Advanced Options` at the bottom of the form and set `Upstream Format` to `Chat Completions (routing required)`. The dropdown offers three options:
![Local routing mapping in the DeepSeek Codex provider form](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
- `Responses (native)` — the upstream natively supports the Responses API; connects directly with no conversion and no routing.
- `Chat Completions (routing required)` — the case this guide covers.
- `Anthropic Messages (routing required)` — the upstream only offers the native Anthropic protocol, which the route converts as well.
The preset already includes DeepSeek's request base URL, default model, model menu, thinking/reasoning parameters, and automatically enables `Needs Local Routing`. You can adjust the default model or model display names if needed; the protocol conversion is handled by the routing layer.
Only `Responses (native)` works without routing takeover; the other two require it. For custom providers, CC Switch infers the thinking parameters from the provider name and address; you only need to expand `Reasoning Capability` and override them manually when that inference is wrong.
> **Converting an existing DeepSeek provider**: change `Upstream Format` to `Responses (native)` — there is no need to delete and recreate it. The next time you switch to it, CC Switch recognises the `deepseek.com` address and applies DeepSeek's official model catalog, so freeform `apply_patch`, the GPT-5 harness, the low/high/max reasoning levels, and web_search all take effect as usual.
>
> The one small difference is the context window: a provider's own saved model rows take priority, so the `1000000` stored before 3.19.1 overrides the officially declared `1048576`, costing you a little over 40k tokens. If that bothers you, open `Advanced Options` → `Model Mapping` and change that row's `Context Window` to `1048576`, or simply create a fresh provider from the preset.
>
> Conversely, to use `deepseek-v4-pro`, change `Upstream Format` back to `Chat Completions`.
>
> One more thing: the official model catalog used by the direct connection requires Codex CLI **0.144.0 or newer** (the freeform `apply_patch` registration it carries needs that release), and CC Switch does not verify this for you. The generated catalog file also grows to roughly 75 KB, because it contains the full GPT-5 harness text.
## Step 2: Enable local routing and route Codex
Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
1. Turn on the main routing switch to start the local service. The default address is `127.0.0.1:15721`.
1. Turn on the `Routing Master Switch` to start the local service. The default address is `127.0.0.1:15721`.
2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use local routing, you can leave Claude and Gemini off.
![Enabling Codex routing on the local routing page](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real DeepSeek key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
After routing is enabled, CC Switch points Codex's live configuration to the local route and manages authentication with a placeholder. The real API key stays in the CC Switch provider configuration and is injected by the local route while forwarding requests, so you do not need to expose the key in Codex's live configuration.
## Step 3: Switch providers and restart Codex
Return to the Codex provider list and click `Enable` on the DeepSeek provider. If you see the `Needs Routing` marker, that provider must be used while routing is running; when the route is not started, CC Switch shows a prompt saying the routing service is required.
Return to the Codex provider list and click `Enable` on the provider you want. If it carries the `Needs Routing` marker while routing is not running, CC Switch shows a prompt saying the routing service is required.
After switching, restart the current Codex terminal session. This is recommended because:
- The Codex process may already have read the old `config.toml`.
- After `model_catalog_json` is generated, the `/model` menu usually needs a fresh process before it refreshes.
Inside Codex, use `/model` to check whether the current model comes from the DeepSeek preset, such as `DeepSeek V4 Flash`. The Codex app currently does not support multi-model selection, so it defaults to the first configured model. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
Inside Codex, use `/model` to check whether the current model comes from the matching preset. Then send a small test prompt and confirm that the request count increases in the routing panel, or that a Codex request appears in usage/request logs.
## How to handle other Chat providers
## Usage attribution changes once you connect directly
DeepSeek, Kimi, MiniMax, SiliconFlow, and other common Chat-format providers already have presets in CC Switch, so use presets first. Only choose custom configuration for providers that are not covered by presets; in that case, fill in the API key, base URL, and models according to the provider's documentation, and set `API Format` to `OpenAI Chat Completions (requires routing)`.
This is worth calling out on its own: once a provider connects directly, its requests no longer pass through the local route, so the per-request proxy usage accounting cannot see them.
If the upstream provider directly supports the OpenAI Responses API, you do not need to enable `Needs Local Routing`; CC Switch can connect through Responses directly without Chat conversion.
The usage itself is not lost — Codex session-log import still records it — but that path carries no provider identity: all Codex usage that did not go through the local proxy is grouped under a single entry named `Codex (Session)`. **To tell them apart, look at the model**: every usage row keeps its own model id, and the usage panel's `Model Stats` table lists them per model, with separate cost and token figures.
If you genuinely need to reconcile by provider — comparing the same model across several aggregators, for instance — keep `Upstream Format` on Chat and leave routing takeover enabled.
## FAQ
@@ -74,18 +107,22 @@ If the upstream provider directly supports the OpenAI Responses API, you do not
Usually Codex routing is not enabled, or the upstream Chat base URL was written directly into Codex manually. Check whether `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
**DeepSeek upstream reports 404**
**The upstream reports 404**
If you are using the built-in DeepSeek preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: the base URL should be the service root, not the full endpoint path with `/chat/completions`.
If you are using a built-in preset, first confirm that the active provider really comes from the preset and that Codex routing is enabled. Only custom providers require extra base URL checks: it should be the service endpoint given in the provider's documentation, not the full endpoint path with `/chat/completions`.
**`/model` does not show DeepSeek models**
**Switching to `deepseek-v4-pro` fails upstream**
DeepSeek has not opened its Codex integration for that model yet. Change that provider's `Upstream Format` back to `Chat Completions (routing required)` and enable routing takeover — that is exactly the path DeepSeek took before 3.19.1, and the route's Responses-to-Chat conversion serves pro as it always did. Alternatively use `deepseek-v4-flash`, which is the preset default and unaffected.
**`/model` does not show the provider's models**
Restart Codex after saving the provider. CC Switch generates `cc-switch-model-catalog.json` and writes its path to `model_catalog_json`, but a running Codex process may not hot-load the model catalog.
The Codex app currently does not support multi-model selection, so it uses the first configured model by default.
**Routing is enabled, but requests still go to the wrong provider**
Confirm that all three states match: the current provider under the Codex tab is DeepSeek; the local routing service is running; and the Codex toggle is enabled under `Routing Enabled`.
Confirm that all three states match: the current provider under the Codex tab is the right one; the local routing service is running; and the Codex toggle is enabled under `Routing Enabled`.
**Can I use an official OpenAI Codex account through local routing?**
@@ -96,6 +133,8 @@ Not recommended. CC Switch blocks switching to official providers while local ro
- [CC Switch User Manual: Add Provider](../user-manual/en/2-providers/2.1-add.md)
- [CC Switch User Manual: Proxy Service](../user-manual/en/4-proxy/4.1-service.md)
- [CC Switch User Manual: App Routing](../user-manual/en/4-proxy/4.2-routing.md)
- [DeepSeek API Docs: Integrate with Codex](https://api-docs.deepseek.com/quick_start/agent_integrations/codex/) (official Codex integration notes, including `wire_api = "responses"` and model coverage)
- [DeepSeek API Docs: Using the Responses API](https://api-docs.deepseek.com/guides/responses_api/)
- [DeepSeek API Docs: Your First API Call](https://api-docs.deepseek.com/)
- [DeepSeek API Docs: Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
- [DeepSeek API Docs: Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
docs/guides/codex-deepseek-routing-guide-ja.md
+60 -21
View File
@@ -1,15 +1,35 @@
# Codex で DeepSeek などの Chat 形式 API を使う: CC Switch ローカルルーティングガイド
> 対象バージョン: CC Switch 3.16.0 およびその前後のバージョン。本記事はリポジトリ内のドキュメントとコードをもとに整理し、OpenAI Chat Completions 互換 API の例として DeepSeek を使用します。スクリーンショットは現在のフロントエンド UI から、実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
> 対象バージョン: CC Switch 3.19.1 以降。本記事はリポジトリ内のドキュメントとコードをもとに整理しています。スクリーンショットは実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
>
> **3.19.1 からの重要な変更**: DeepSeek プリセットはネイティブ Responses による直結に変わり、ローカルルーティングを必要としなくなりました。ただし、このルーティング変換の経路がなくなったわけではありません——`deepseek-v4-pro` を使う場合、アップグレード前に保存したプロバイダー、そして Kimi や Zhipu GLM など Chat 形式のままのプロバイダーでは、引き続きこの経路が必要です。まず次のセクションで、自分がどのケースに当てはまるかを確認してください。
## まず、このガイドが今も必要か確認する
判別方法は 1 つだけです。Codex プロバイダーカードに `ルーティングが必要` バッジが付いているかを見てください。
![Codex プロバイダー一覧のローカルルーティング必須マーク](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
- **`ルーティングが必要` バッジあり** → このプロバイダーは Chat 形式で、本記事がそのまま当てはまります。
- **バッジなし** → すでにネイティブ Responses で直結しているため、本記事のルーティング手順は不要です。そのまま使えます。
- **`ルーティング非対応` バッジあり** → 公式プロバイダーであり、CC Switch はローカルルーティング経由での使用をブロックします（末尾のよくある質問を参照）。
このバッジはプロバイダー保存時に記録された API 形式で決まるため、CC Switch をアップグレードしても既存プロバイダーの挙動は**変わりません**。DeepSeek に関しては、3.19.1 へのアップグレード後に次の 3 つのケースがあります。
| あなたの状況 | ルーティングは必要か | 説明 |
|---|---|---|
| 3.19.1 より前に保存した DeepSeek プロバイダー | **必要**（バッジも表示されたまま） | プリセットの変更は新規作成したプロバイダーにのみ影響し、保存済みの設定はそのまま維持されます。直結に変えたい場合は Step 1 の末尾を参照してください |
| 3.19.1 以降にプリセットから新規作成した DeepSeek | 不要 | `api.deepseek.com` へ直結し、DeepSeek 公式のモデルカタログを取得します |
| `deepseek-v4-pro` を使いたい | **必要** | DeepSeek はこのモデルの Codex 連携をまだ開放しておらず（公式の見込みでは 2026 年 8 月初旬）、直結では上流エラーになります。Chat + ルーティングを通す必要があります |
DeepSeek 以外にも、Kimi、Zhipu GLM、SiliconFlow、ModelScope など多くのプロバイダーが Chat 形式のままであり、本記事はそれらにも完全に当てはまります。以下の DeepSeek を該当のプリセットに読み替えてください。
## ローカルルーティングが必要な理由
新しい Codex CLI は OpenAI Responses API を前提にしています。一方で DeepSeek、Kimi、MiniMax、SiliconFlow など多くのプロバイダーが実際に公開しているのは OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Chat エンドポイントをそのまま Codex 設定に入れると、モデル一覧が合わない、リクエストが 404/400 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
新しい Codex CLI は OpenAI Responses API を前提にしています。一方で多くのプロバイダーが実際に公開しているのは OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Chat エンドポイントをそのまま Codex 設定に入れると、モデル一覧が合わない、リクエストが 404/400 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。
![Codex プロバイダー一覧のローカルルーティング必須マーク](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
この経路は主に 4 つのステップに分かれます：
1. Codex ルーティングを有効にすると、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` は維持されます。
@@ -17,28 +37,39 @@ CC Switch では、Codex が常にローカルルートへ接続し、Responses
3. ルートは `/responses` または `/v1/responses` を `/chat/completions` に書き換え、Responses のリクエストボディを Chat のリクエストボディへ変換します。
4. 上流から返ってきた後、ルートは Chat の JSON または SSE ストリームを Responses JSON/SSE へ変換して返します。
上流がもともとネイティブ Responses のプロバイダー（現在の DeepSeek プリセットなど）では、ステップ 2〜4 は発生しません。リクエストはそのまま上流へ送られ、形式の書き換えは一切行われません。
## 事前準備
先に次の 3 つを用意してください：
- インストール済みで起動できる CC Switch。
- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/config.toml` のディレクトリ構造が存在していること。
- DeepSeek または同種の Chat Completions プロバイダーの API Key。
- 対象プロバイダーの API Key。
DeepSeek 公式ドキュメントでは、OpenAI 互換 base URL は現在 `https://api.deepseek.com`（他のプロバイダーでは `/v1` 付きの base URL もよくあります）、Chat API のパスは `/chat/completions` と記載されています。CC Switch の DeepSeek プリセットにはこれらの情報がすでに入っているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。
DeepSeek を例にとると、公式ドキュメントでは OpenAI 互換 base URL は `https://api.deepseek.com`（他のプロバイダーでは `/v1` 付きやより長いパスの base URL もよくあります。たとえば Zhipu GLM は `https://open.bigmodel.cn/api/coding/paas/v4` です）、Chat API のパスは `/chat/completions` と記載されています。CC Switch のプリセットにはこれらの情報がすでに入っているため、まずはプリセットを使い、エンドポイントパスを手で組み立てる必要はありません。
## Step 1: Codex プロバイダーを追加する
CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。
内蔵プリセットの `DeepSeek` を選びます。必要なのは次の 2 つだけです：
**プリセットを使う**（推奨）: プリセット一覧から対象プロバイダーを選び、API Key を入力して保存するだけです。プリセットにはリクエスト先、デフォルトモデル、モデルメニューがすでに含まれ、上流フォーマットも自動的に設定されます。Chat 形式のプリセットは保存するとカードに `ルーティングが必要` バッジが表示されます。thinking / reasoning パラメータもプリセットで設定済みのため、手動入力は不要です。
- DeepSeek API Key を入力する。
- プロバイダーを保存する。
**カスタム設定を使う**: 相手側のドキュメントに従って API Key と base URL を入力し、フォーム下部の `高級オプション` を展開して、`上流フォーマット` を `Chat Completions（ルーティング必須）` に設定します。このドロップダウンには 3 つの選択肢があります：
![DeepSeek Codex プロバイダーフォームのローカルルーティング設定](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
- `Responses（ネイティブ）`——上流が Responses API をネイティブにサポートしている場合。変換なしで直結でき、ルーティングは不要です。
- `Chat Completions（ルーティング必須）`——本記事が扱うケースです。
- `Anthropic Messages（ルーティング必須）`——上流がネイティブ Anthropic プロトコルのみを提供している場合。こちらもルーティングが変換します。
プリセットには DeepSeek のリクエスト先、デフォルトモデル、モデルメニュー、thinking/reasoning パラメータがすでに含まれており、`ローカルルーティングが必要` も自動的に有効になります。必要に応じてデフォルトモデルやモデル表示名を調整できますが、プロトコル変換はルーティング層に任せれば十分です。
ルーティング接管が不要なのは `Responses（ネイティブ）` だけで、残りの 2 つは必要です。カスタムプロバイダーの thinking パラメータは CC Switch が名前とアドレスから自動推論するため、推論が正しくないときにだけ `思考能力` を展開して手動で上書きしてください。
> **既存の DeepSeek プロバイダーを移行する場合**: `上流フォーマット` を `Responses（ネイティブ）` に変更するだけでよく、削除して作り直す必要はありません。次回そのプロバイダーへ切り替えたとき、CC Switch が `deepseek.com` のアドレスを認識して DeepSeek 公式のモデルカタログを適用するため、freeform `apply_patch`、GPT-5 harness、low/high/max の思考レベル、web_search はいずれも通常どおり有効になります。
>
> 唯一わずかに異なるのはコンテキストウィンドウです。プロバイダー自身が保存したモデル行のほうが優先されるため、3.19.1 より前に保存された `1000000` が公式宣言の `1048576` を上書きし、4 万トークン強が失われます。気になる場合は `高級オプション` → `モデルマッピング` でその行の `コンテキストウィンドウ` を `1048576` に変更するか、いっそプリセットから新規作成してください。
>
> 逆に `deepseek-v4-pro` を使いたい場合は、`上流フォーマット` を `Chat Completions` に戻します。
>
> なお、直結で使われる公式モデルカタログは Codex CLI **0.144.0 以降**を必要とします（カタログに含まれる freeform `apply_patch` の登録がこのバージョンを要求します）。CC Switch はこれを検証しません。また、生成されるカタログファイルは GPT-5 harness の全文を含むため 75 KB 程度まで大きくなります。
## Step 2: ローカルルーティングを有効にして Codex をルーティングする
@@ -49,24 +80,26 @@ CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラ
![ローカルルーティング画面で Codex ルーティングを有効化](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の DeepSeek Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の API Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
## Step 3: プロバイダーを切り替えて Codex を再起動する
Codex プロバイダー一覧に戻り、DeepSeek プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示が見える場合、そのプロバイダーはルーティング実行中に使う必要があります。ルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
Codex プロバイダー一覧に戻り、対象プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示があるのにルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：
- Codex プロセスがすでに古い `config.toml` を読み込んでいる可能性があります。
- `model_catalog_json` の生成後、`/model` メニューの更新には通常、新しいプロセスが必要です。
Codex に入ったら、`/model` で現在のモデルが DeepSeek プリセット由来かどうかを確認します。たとえば `DeepSeek V4 Flash` などです。現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
Codex に入ったら、`/model` で現在のモデルが該当プリセット由来かどうかを確認します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
## 他の Chat プロバイダーの場合
## 直結に切り替えると、使用量の帰属が変わる
DeepSeek、Kimi、MiniMax、SiliconFlow など一般的な Chat 形式プロバイダーは CC Switch にプリセットがあるため、まずはプリセットを使ってください。プリセットにないプロバイダーだけ、カスタム設定を選びます。その場合は相手側のドキュメントに従って API Key、base URL、モデルを入力し、`API 形式` を `OpenAI Chat Completions (ルーティングが必要)` に設定します。
これは単独で触れておく価値があります。プロバイダーが直結に変わると、そのリクエストはローカルルートを通らなくなるため、リクエスト単位で計上するプロキシ使用量統計からは見えなくなります。
上流が OpenAI Responses API を直接サポートしている場合は、`ローカルルーティングが必要` を有効にする必要はありません。その場合、CC Switch は Responses のまま直結でき、Chat 変換は行いません。
使用量そのものが失われるわけではありません——Codex のセッションログ取り込みは通常どおり記録します——ただしこの経路はプロバイダーの識別情報を持ちません。ローカルプロキシを通らなかった Codex の使用量は、すべて `Codex (Session)` という 1 つの項目にまとめられます。**見分けるにはモデルを見てください**: 各使用量レコードはそれぞれのモデル ID を保持しており、使用量パネルの `モデル統計` がモデルごとに行を分けて表示するため、費用もトークンも別々に確認できます。
プロバイダー単位で突き合わせる必要が本当にある場合（複数の集約サービスで同じモデルを比較する場合など）は、`上流フォーマット` を Chat のままにして、ルーティング接管を有効にしておいてください。
## よくある質問
@@ -74,18 +107,22 @@ DeepSeek、Kimi、MiniMax、SiliconFlow など一般的な Chat 形式プロバ
多くの場合、Codex ルーティングが有効になっていないか、上流 Chat base URL を手動で Codex に直接書いています。`~/.codex/config.toml` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
**DeepSeek 上流が 404 を返す**
**上流が 404 を返す**
内蔵 DeepSeek プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL はサービスのルートであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
内蔵プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL は相手側のドキュメントが示すサービスエンドポイントであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
**`/model` に DeepSeek モデルが表示されない**
**`deepseek-v4-pro` に切り替えると上流エラーになる**
DeepSeek はこのモデルの Codex 連携をまだ開放していません。そのプロバイダーの `上流フォーマット` を `Chat Completions（ルーティング必須）` に戻し、ルーティング接管を有効にしてください——これは 3.19.1 より前に DeepSeek が通っていた経路そのもので、ルートの Responses→Chat 変換は従来どおり pro に対応しています。または、プリセットのデフォルト値であり影響を受けない `deepseek-v4-flash` を使ってください。
**`/model` にプロバイダーのモデルが表示されない**
プロバイダーを保存した後、Codex を再起動してください。CC Switch は `cc-switch-model-catalog.json` を生成し、そのパスを `model_catalog_json` に書き込みますが、実行中の Codex プロセスがモデルカタログをホットロードするとは限りません。
現在の Codex app は複数モデル選択に対応していないため、設定内の最初のモデルをデフォルトで使用します。
**ルーティングを有効にしたのに、リクエストが別のプロバイダーへ行く**
次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが DeepSeek であること、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
次の 3 つの状態が一致しているか確認してください：Codex タブの現在のプロバイダーが正しいこと、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
**公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか**
@@ -96,6 +133,8 @@ DeepSeek、Kimi、MiniMax、SiliconFlow など一般的な Chat 形式プロバ
- [CC Switch ユーザーマニュアル: プロバイダーの追加](../user-manual/ja/2-providers/2.1-add.md)
- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
- [DeepSeek API Docs: Integrate with Codex](https://api-docs.deepseek.com/quick_start/agent_integrations/codex/)（公式 Codex 連携の説明。`wire_api = "responses"` と対応モデルの範囲を含む）
- [DeepSeek API Docs: Using the Responses API](https://api-docs.deepseek.com/guides/responses_api/)
- [DeepSeek API Docs: Your First API Call](https://api-docs.deepseek.com/)
- [DeepSeek API Docs: Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
- [DeepSeek API Docs: Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)
docs/guides/codex-deepseek-routing-guide-zh.md
+60 -21
View File
@@ -1,15 +1,35 @@
# 在 Codex 中用 DeepSeek 这类 Chat 格式 API：CC Switch 本地路由攻略
> 适用版本：CC Switch 3.16.0 及附近版本。本文根据仓库内文档与代码整理，并用 DeepSeek 作为 OpenAI Chat Completions 兼容接口的示例。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。
> 适用版本：CC Switch 3.19.1 及以上。本文根据仓库内文档与代码整理。截图使用去敏示例数据生成，避免泄露真实 API Key 或账户余额。
>
> **3.19.1 起有重要变化**：DeepSeek 预设已改为原生 Responses 直连，不再需要本地路由。但这条路由转换的路径并没有作废——它仍是 `deepseek-v4-pro`、升级前已保存的供应商，以及 Kimi、智谱 GLM 等 Chat 格式供应商的必经之路。请先读下一节，确认你属于哪种情况。
## 先确认你是否还需要这篇攻略
判断方法只有一个，看 Codex 供应商卡片上有没有 `需要路由` 徽章：
![Codex 供应商列表里的需要路由标记](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
- **带 `需要路由` 徽章** → 这个供应商走 Chat 格式，本文全部适用。
- **没有徽章** → 它已经是 Responses 原生直连，本文的路由步骤对它没有意义，可以直接用。
- **带 `不支持路由` 徽章** → 这是官方供应商，CC Switch 会阻止它走本地路由（见文末常见问题）。
徽章由供应商保存时记录的 API 格式决定，所以升级 CC Switch **不会**改变已有供应商的行为。具体到 DeepSeek，升级到 3.19.1 之后有三种情况：
| 你的情况 | 是否需要路由 | 说明 |
|---|---|---|
| 3.19.1 之前保存的 DeepSeek 供应商 | **需要**，仍带徽章 | 预设改动只影响新建的供应商，已保存的配置原样保留；想改走直连见第一步末尾 |
| 3.19.1 之后用预设新建的 DeepSeek | 不需要 | 直连 `api.deepseek.com`，并会拿到 DeepSeek 官方的模型目录 |
| 想用 `deepseek-v4-pro` | **需要** | DeepSeek 官方尚未为该模型开通 Codex 集成（官方预计 2026 年 8 月初），直连会上游报错；必须走 Chat + 路由 |
除 DeepSeek 外，Kimi、智谱 GLM、SiliconFlow、ModelScope 等大量供应商仍是 Chat 格式，本文对它们完全适用——把下文中的 DeepSeek 换成对应预设即可。
## 为什么需要本地路由
新版 Codex CLI 面向的是 OpenAI Responses API，而 DeepSeek、Kimi、MiniMax、SiliconFlow 等很多供应商实际暴露的是 OpenAI Chat Completions 形态，也就是 `/chat/completions`。这两种协议的请求体、流式事件和返回结构不同，直接把 Chat 接口填进 Codex 配置里，常见结果就是模型列表不对、请求 404/400，或者流式响应无法被 Codex 正确解析。
新版 Codex CLI 面向的是 OpenAI Responses API，而很多供应商实际暴露的是 OpenAI Chat Completions 形态，也就是 `/chat/completions`。这两种协议的请求体、流式事件和返回结构不同，直接把 Chat 接口填进 Codex 配置里，常见结果就是模型列表不对、请求 404/400，或者流式响应无法被 Codex 正确解析。
CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由在内部识别当前供应商是否是 Chat 格式，再把请求改写成 Chat Completions 发给上游，最后把 Chat 响应转换回 Responses 形态返回给 Codex。
![Codex 供应商列表里的需要路由标记](../images/codex-deepseek-routing/01-codex-providers-require-routing.png)
这条链路主要分成四步：
1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
@@ -17,28 +37,39 @@ CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发
3. 路由把 `/responses` 或 `/v1/responses` 改写到 `/chat/completions`，并把 Responses 请求体转换成 Chat 请求体。
4. 上游返回后，路由再把 Chat 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE。
供应商原生就是 Responses 的（如现在的 DeepSeek 预设），第 2～4 步不发生：请求直接发往上游，不做任何格式改写。
## 准备工作
你需要先准备好三样东西：
- 已安装并能启动的 CC Switch。
- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/config.toml` 目录结构存在。
- DeepSeek 或同类 Chat Completions 供应商的 API Key。
- 目标供应商的 API Key。
DeepSeek 官方文档目前写明 OpenAI 兼容 base URL 是 `https://api.deepseek.com`（其他供应商常见的是带 `/v1` 后缀的 base URL），Chat API 路径是 `/chat/completions`；CC Switch 的 DeepSeek 预设已经按这些信息配好，请优先使用预设，不需要手动拼接口路径。
以 DeepSeek 为例，官方文档写明 OpenAI 兼容 base URL 是 `https://api.deepseek.com`（其他供应商常见的是带 `/v1` 或更长路径的 base URL，例如智谱 GLM 是 `https://open.bigmodel.cn/api/coding/paas/v4`），Chat API 路径是 `/chat/completions`。CC Switch 的预设已按这些信息配好，请优先使用预设，不需要手动拼接口路径。
## 第一步：添加 Codex 供应商
打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商。
选择内置预设里的 `DeepSeek`，只需要做两件事：
**用预设**（推荐）：在预设列表里选中目标供应商，填入 API Key，保存即可。预设已经内置请求地址、默认模型、模型菜单，并会自动设好上游格式；Chat 格式的预设保存后卡片上就会出现 `需要路由` 徽章。思考参数（thinking / reasoning）预设已自动配置好，不需要手动填。
- 填入 DeepSeek API Key。
- 保存供应商。
**用自定义配置**：按对方文档填 API Key 和 base URL，然后展开表单底部的 `高级选项`，把 `上游格式` 选为 `Chat Completions（需开启路由）`。这个下拉共有三个选项：
![DeepSeek Codex 供应商表单中的本地路由映射](../images/codex-deepseek-routing/02-deepseek-codex-routing-form.png)
- `Responses（原生）`——上游原生支持 Responses API，直连不转换，无需路由。
- `Chat Completions（需开启路由）`——本文讲的情况。
- `Anthropic Messages（需开启路由）`——上游只提供原生 Anthropic 协议，同样由路由转换。
预设已经内置 DeepSeek 的请求地址、默认模型、模型菜单、thinking/reasoning 参数，并会自动打开 `需要本地路由映射`。你可以按需调整默认模型或模型显示名；协议转换交给路由层完成即可。
只有 `Responses（原生）` 不需要开启路由接管，另外两个都需要。自定义供应商的思考参数由 CC Switch 按名称与地址自动推断，只有在识别不准时才需要展开 `思考能力` 手动覆盖。
> **改造已有的 DeepSeek 供应商**：把 `上游格式` 改成 `Responses（原生）` 即可，不必删掉重建。下次切换到它时，CC Switch 会认出 `deepseek.com` 地址并套用 DeepSeek 官方的模型目录，freeform `apply_patch`、GPT-5 harness、low/high/max 思考档与 web_search 都会照常生效。
>
> 唯一的小差别是上下文窗口：供应商自己保存的模型行优先级更高，3.19.1 之前存下的 `1000000` 会盖掉官方声明的 `1048576`，少 4 万多 token。介意的话，在 `高级选项` → `模型映射` 里把该行的 `上下文窗口` 改成 `1048576` 就行，或者干脆用预设新建一个。
>
> 反过来，想用 `deepseek-v4-pro`，就把 `上游格式` 改回 `Chat Completions`。
>
> 另外，直连所用的官方模型目录要求 Codex CLI **0.144.0 或更新**（它带的 freeform `apply_patch` 注册需要这个版本），CC Switch 不会替你校验；生成的目录文件也会涨到 75 KB 左右，因为其中包含完整的 GPT-5 harness 文本。
## 第二步：开启本地路由并接管 Codex
@@ -49,24 +80,26 @@ DeepSeek 官方文档目前写明 OpenAI 兼容 base URL 是 `https://api.deepse
![本地路由页面中启用 Codex 接管](../images/codex-deepseek-routing/03-local-route-codex-takeover.png)
接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 DeepSeek Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。
接管后，CC Switch 会把 Codex 的 live 配置指向本机路由，并用占位符管理认证。真实 API Key 仍保存在 CC Switch 的 Provider 配置里，由本地路由在转发时注入，不需要你把 Key 暴露给 Codex live 配置。
## 第三步：切换供应商并重启 Codex
回到 Codex 供应商列表，点击 DeepSeek 供应商的 `启用`。如果看到 `需要路由` 标记，说明这个供应商必须在路由运行时使用；没有启动路由时，CC Switch 会弹出“需要路由服务才能正常使用”的提示。
回到 Codex 供应商列表，点击目标供应商的 `启用`。如果它带 `需要路由` 标记而路由没有启动，CC Switch 会弹出“需要路由服务才能正常使用”的提示。
切换后建议重启当前 Codex 终端会话。原因是：
- Codex 进程可能已经读取过旧的 `config.toml`。
- `model_catalog_json` 生成后，`/model` 菜单通常需要新进程才能刷新。
进入 Codex 后，可以用 `/model` 查看当前模型是否来自 DeepSeek 预设，例如 `DeepSeek V4 Flash`。目前 Codex app 不支持多模型选择时，会默认使用配置里的第一个模型。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。
进入 Codex 后，可以用 `/model` 查看当前模型是否来自对应预设。随后发一个小问题，确认路由面板的请求数增长，或者在用量/请求日志里看到 Codex 请求即可。
## 其它 Chat 供应商怎么处理
## 走直连之后，用量归属会变
DeepSeek、Kimi、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Switch 里已有预设，优先用预设即可。只有预设里没有的供应商，才需要选择自定义配置；这时按对方文档填 API Key、base URL 和模型，并把 `API 格式` 选为 `OpenAI Chat Completions (需开启路由)`。
这一点值得单独提醒：供应商改走直连后，它的请求不再经过本地路由，按请求计费的代理用量统计也就看不到它了。
如果上游直接支持 OpenAI Responses API，就不需要打开 `需要本地路由映射`；这时 CC Switch 可以按 Responses 直连，不做 Chat 转换。
用量本身不会丢——Codex 的会话日志导入照常记录——但这条路径不携带供应商身份：所有没走本地代理的 Codex 用量会一起归入名为 `Codex (Session)` 的条目。**要区分它们，看模型**：每条用量记录都带着自己的模型 ID，用量面板的「模型统计」按模型逐行列出，费用与 token 都是分开的。
如果你确实需要按供应商维度对账（比如比较多个聚合商上的同一个模型），那就保持 `上游格式` 为 Chat 并开着路由接管。
## 常见问题
@@ -74,18 +107,22 @@ DeepSeek、Kimi、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Swi
通常是没有开启 Codex 接管，或者你手动把上游 Chat base URL 直接写给了 Codex。检查 `~/.codex/config.toml` 是否指向 `http://127.0.0.1:15721/v1`。
**DeepSeek 上游报 404**
**上游报 404**
如果用的是内置 DeepSeek 预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是服务根地址，而不是带 `/chat/completions` 的完整接口路径。
如果用的是内置预设，先确认当前供应商确实来自预设，并且 Codex 路由已启用。只有在使用自定义供应商时，才需要额外检查 base URL：它应该是对方文档给出的服务端点，而不是带 `/chat/completions` 的完整接口路径。
**`/model` 看不到 DeepSeek 模型**
**切到 `deepseek-v4-pro` 后上游报错**
DeepSeek 官方尚未为该模型开通 Codex 集成。把这个供应商的 `上游格式` 改回 `Chat Completions（需开启路由）` 并开启路由接管即可——这正是 3.19.1 之前 DeepSeek 走的路径，路由的 Responses→Chat 转换照常支持 pro。或者改用 `deepseek-v4-flash`，它是预设默认值，不受影响。
**`/model` 看不到供应商的模型**
保存供应商后重启 Codex。CC Switch 会生成 `cc-switch-model-catalog.json` 并把路径写入 `model_catalog_json`，但正在运行的 Codex 进程不一定会热加载模型目录。
目前 Codex app 不支持多模型选择，默认使用配置的第一个模型。
**开了路由但请求仍走错供应商**
确认三处状态一致：Codex 标签下当前供应商是 DeepSeek；本地路由服务正在运行；`路由启用` 里 Codex 开关已打开。
确认三处状态一致：Codex 标签下当前供应商正确；本地路由服务正在运行；`路由启用` 里 Codex 开关已打开。
**可以用官方 OpenAI Codex 账号走本地路由吗**
@@ -96,6 +133,8 @@ DeepSeek、Kimi、MiniMax、SiliconFlow 等常见 Chat 格式供应商在 CC Swi
- [CC Switch 用户手册：添加供应商](../user-manual/zh/2-providers/2.1-add.md)
- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
- [DeepSeek API 文档：Integrate with Codex](https://api-docs.deepseek.com/quick_start/agent_integrations/codex/)（官方 Codex 集成说明，含 `wire_api = "responses"` 与模型支持范围）
- [DeepSeek API 文档：Using the Responses API](https://api-docs.deepseek.com/guides/responses_api/)
- [DeepSeek API 文档：Your First API Call](https://api-docs.deepseek.com/)
- [DeepSeek API 文档：Create Chat Completion](https://api-docs.deepseek.com/api/create-chat-completion)
- [DeepSeek API 文档：Multi-round Conversation](https://api-docs.deepseek.com/guides/multi_round_chat)