mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-08-03 19:12:04 +08:00
Jason
a4bba43f73
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.
141 lines
17 KiB
Markdown
141 lines
17 KiB
Markdown
# Codex で DeepSeek などの Chat 形式 API を使う: CC Switch ローカルルーティングガイド
|
|
|
|
> 対象バージョン: CC Switch 3.19.1 以降。本記事はリポジトリ内のドキュメントとコードをもとに整理しています。スクリーンショットは実際の API Key やアカウント残高が漏れないよう匿名化したサンプルデータで生成しています。
|
|
>
|
|
> **3.19.1 からの重要な変更**: DeepSeek プリセットはネイティブ Responses による直結に変わり、ローカルルーティングを必要としなくなりました。ただし、このルーティング変換の経路がなくなったわけではありません——`deepseek-v4-pro` を使う場合、アップグレード前に保存したプロバイダー、そして Kimi や Zhipu GLM など Chat 形式のままのプロバイダーでは、引き続きこの経路が必要です。まず次のセクションで、自分がどのケースに当てはまるかを確認してください。
|
|
|
|
## まず、このガイドが今も必要か確認する
|
|
|
|
判別方法は 1 つだけです。Codex プロバイダーカードに `ルーティングが必要` バッジが付いているかを見てください。
|
|
|
|
|
|
|
|
- **`ルーティングが必要` バッジあり** → このプロバイダーは 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 を前提にしています。一方で多くのプロバイダーが実際に公開しているのは OpenAI Chat Completions 形式、つまり `/chat/completions` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造が異なります。Chat エンドポイントをそのまま Codex 設定に入れると、モデル一覧が合わない、リクエストが 404/400 になる、ストリーミングレスポンスを Codex が正しく解析できない、といった問題が起きがちです。
|
|
|
|
CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルート内部で現在のプロバイダーが Chat 形式かどうかを判定し、必要ならリクエストを Chat Completions に書き換えて上流へ送り、最後に Chat レスポンスを Codex が理解できる Responses 形式へ戻します。
|
|
|
|
この経路は主に 4 つのステップに分かれます：
|
|
|
|
1. Codex ルーティングを有効にすると、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` は維持されます。
|
|
2. Provider の `meta.apiFormat = "openai_chat"` が、実際の上流は Chat Completions だとルートに伝えます。
|
|
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` のディレクトリ構造が存在していること。
|
|
- 対象プロバイダーの API Key。
|
|
|
|
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` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。
|
|
|
|
**プリセットを使う**（推奨）: プリセット一覧から対象プロバイダーを選び、API Key を入力して保存するだけです。プリセットにはリクエスト先、デフォルトモデル、モデルメニューがすでに含まれ、上流フォーマットも自動的に設定されます。Chat 形式のプリセットは保存するとカードに `ルーティングが必要` バッジが表示されます。thinking / reasoning パラメータもプリセットで設定済みのため、手動入力は不要です。
|
|
|
|
**カスタム設定を使う**: 相手側のドキュメントに従って API Key と base URL を入力し、フォーム下部の `高級オプション` を展開して、`上流フォーマット` を `Chat Completions（ルーティング必須）` に設定します。このドロップダウンには 3 つの選択肢があります：
|
|
|
|
- `Responses（ネイティブ）`——上流が Responses API をネイティブにサポートしている場合。変換なしで直結でき、ルーティングは不要です。
|
|
- `Chat Completions（ルーティング必須）`——本記事が扱うケースです。
|
|
- `Anthropic Messages（ルーティング必須）`——上流がネイティブ Anthropic プロトコルのみを提供している場合。こちらもルーティングが変換します。
|
|
|
|
ルーティング接管が不要なのは `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 をルーティングする
|
|
|
|
設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、次の 2 つのスイッチを設定します：
|
|
|
|
1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します。デフォルトアドレスは `127.0.0.1:15721` です。
|
|
2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
|
|
|
|
|
|
|
|
ルーティングを有効にすると、CC Switch は Codex の live 設定をローカルルートへ向け、認証はプレースホルダーで管理します。実際の API Key は CC Switch の Provider 設定内に残り、ローカルルートが転送時に注入します。そのため、Codex の live 設定に Key を露出させる必要はありません。
|
|
|
|
## Step 3: プロバイダーを切り替えて Codex を再起動する
|
|
|
|
Codex プロバイダー一覧に戻り、対象プロバイダーの `有効化` をクリックします。`ルーティングが必要` の表示があるのにルーティングが起動していない場合、CC Switch は「ルーティングサービスが必要」という趣旨のメッセージを表示します。
|
|
|
|
切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。理由は次のとおりです：
|
|
|
|
- Codex プロセスがすでに古い `config.toml` を読み込んでいる可能性があります。
|
|
- `model_catalog_json` の生成後、`/model` メニューの更新には通常、新しいプロセスが必要です。
|
|
|
|
Codex に入ったら、`/model` で現在のモデルが該当プリセット由来かどうかを確認します。その後、小さな質問を 1 つ送って、ルーティングパネルのリクエスト数が増えるか、usage / リクエストログに Codex リクエストが出るかを確認します。
|
|
|
|
## 直結に切り替えると、使用量の帰属が変わる
|
|
|
|
これは単独で触れておく価値があります。プロバイダーが直結に変わると、そのリクエストはローカルルートを通らなくなるため、リクエスト単位で計上するプロキシ使用量統計からは見えなくなります。
|
|
|
|
使用量そのものが失われるわけではありません——Codex のセッションログ取り込みは通常どおり記録します——ただしこの経路はプロバイダーの識別情報を持ちません。ローカルプロキシを通らなかった Codex の使用量は、すべて `Codex (Session)` という 1 つの項目にまとめられます。**見分けるにはモデルを見てください**: 各使用量レコードはそれぞれのモデル ID を保持しており、使用量パネルの `モデル統計` がモデルごとに行を分けて表示するため、費用もトークンも別々に確認できます。
|
|
|
|
プロバイダー単位で突き合わせる必要が本当にある場合（複数の集約サービスで同じモデルを比較する場合など）は、`上流フォーマット` を Chat のままにして、ルーティング接管を有効にしておいてください。
|
|
|
|
## よくある質問
|
|
|
|
**Codex が 404 を返す、または `/responses` が見つからない**
|
|
|
|
多くの場合、Codex ルーティングが有効になっていないか、上流 Chat base URL を手動で Codex に直接書いています。`~/.codex/config.toml` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
|
|
|
|
**上流が 404 を返す**
|
|
|
|
内蔵プリセットを使っている場合は、まず現在のプロバイダーが本当にプリセット由来であること、そして Codex ルーティングが有効であることを確認してください。カスタムプロバイダーを使っている場合だけ、base URL を追加で確認します。base URL は相手側のドキュメントが示すサービスエンドポイントであり、`/chat/completions` 付きの完全なエンドポイントパスではありません。
|
|
|
|
**`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 タブの現在のプロバイダーが正しいこと、ローカルルーティングサービスが実行中であること、`ルーティング有効` で Codex スイッチがオンであること。
|
|
|
|
**公式 OpenAI Codex アカウントをローカルルーティング経由で使えますか**
|
|
|
|
おすすめしません。CC Switch はローカルルーティング有効中、公式プロバイダーへの切り替えをブロックします。プロキシ経由で公式 API にアクセスすると、アカウントリスクが発生する可能性があるためです。ルーティングは主にサードパーティ、集約サービス、またはプロトコル変換のための機能です。
|
|
|
|
## 参考リンク
|
|
|
|
- [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)
|