mirror of
https://github.com/farion1231/cc-switch.git
synced 2026-07-24 12:44:18 +08:00
docs(guides): add Codex + Claude local routing guide in three languages
Step-by-step guide for the v3.17.0 native Anthropic Messages upstream: add a custom Codex provider pointed at a Claude-family /v1/messages gateway, pick the anthropic upstream format, enable local routing, and verify the chain. Covers the auth-field choice (Bearer vs x-api-key), the Claude Code impersonation toggle, the 8192 max-output fallback, and a FAQ entry for gateways that restrict keys to Claude Code only. Includes four UI screenshots captured from the real 3.17.0 app with sample data, and links the guide from the v3.17.0 release notes in all three languages.
This commit is contained in:
Jason
@@ -0,0 +1,129 @@
|
||||
# Using Claude in Codex: CC Switch Local Routing Guide
|
||||
|
||||
> Applies to CC Switch 3.17.0 and later (the Anthropic Messages upstream was introduced in 3.17.0). This guide is based on the repository documentation and code, and uses a Claude-family relay gateway as the example. Screenshots are generated from the current frontend UI with de-identified sample data to avoid exposing a real API key.
|
||||
|
||||
## Why local routing is needed
|
||||
|
||||
The newer Codex CLI targets the OpenAI Responses API, while the various Claude-family relay gateways and internal enterprise gateways expose the Anthropic Messages protocol — that is, `/v1/messages`. These two protocols use completely different request bodies, streaming events, and response structures, so putting such a gateway's endpoint directly into Codex configuration can only result in a request to `/responses` coming back 404.
|
||||
|
||||
This feature targets the scenario where all you have is a `/v1/messages` endpoint: you have a key for some Claude-family relay gateway and want to run Claude-family models with Codex's interaction style; or your company has banned the Claude Code client for compliance reasons and kept only an approved Claude-family gateway — the model itself is available, and all that's missing is a permitted client, which Codex can now fill.
|
||||
|
||||
CC Switch's approach is to keep Codex always talking to the local route and still sending Responses API requests; once the route detects that the active provider is Anthropic-format, it converts the request into Anthropic Messages for the upstream, then converts the response back into the Responses shape it returns to Codex.
|
||||
|
||||
|
||||
|
||||
The chain has four main steps:
|
||||
|
||||
1. When Codex is taken over, the local configuration is written as `http://127.0.0.1:15721/v1`, and `wire_api = "responses"` is forcibly kept in place.
|
||||
2. The provider's `anthropic` upstream format tells the route that the real upstream speaks the Anthropic Messages protocol.
|
||||
3. The route rewrites `/responses` to `/v1/messages` and converts the Responses request body into an Anthropic request body.
|
||||
4. After the upstream responds, the route converts the Anthropic JSON or SSE back into the Responses JSON/SSE that Codex understands — reasoning content, tool calls, and images are all within the conversion scope.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Prepare these three things first:
|
||||
|
||||
- CC Switch installed and able to start (3.17.0 or later).
|
||||
- Codex CLI installed and run at least once, so the `~/.codex/` directory structure exists.
|
||||
- An API key that can reach an Anthropic Messages protocol endpoint (`/v1/messages`) — from some Claude-family relay gateway, or an internal enterprise Claude gateway; follow the gateway's documentation for its endpoint and auth method. Note: some providers restrict their Claude API to Claude Code only, so such a key may error out when used through Codex — if you're unsure, check with your provider first.
|
||||
|
||||
The Codex tab currently has no built-in Anthropic preset, so the steps below use the `Custom Configuration` path — just four or five fields from start to finish.
|
||||
|
||||
## Step 1: Add a Codex provider
|
||||
|
||||
Open CC Switch, switch to the top-level `Codex` tab, click the plus button in the upper-right corner to add a provider, keep the default `Custom Configuration`, then fill in:
|
||||
|
||||
- **Provider Name**: anything you like, e.g. `Claude Gateway`.
|
||||
- **API Key**: your gateway key. The real key is stored only in CC Switch and injected by the local route when forwarding, so it never enters Codex's live config.
|
||||
- **API Request URL**: just the gateway's service root, e.g. `https://claude-gateway.example.com`. It works with or without a trailing `/v1` — the route sends requests to `/v1/messages` automatically; don't assemble `/v1/messages` yourself (if your gateway documentation gives you a complete messages URL, you can turn on the `Full URL` toggle next to it and paste it verbatim). The yellow hint below the address bar, "compatible with OpenAI Response format", is generic copy written for the direct Responses scenario; when you choose the Anthropic format, just fill it in as this guide describes.
|
||||
- **Default Model**: enter a Claude model id the gateway recognizes, e.g. `claude-sonnet-5`; follow the model names in the gateway's documentation.
|
||||
|
||||
Then expand `Advanced Options` and change `Upstream Format` from the default `Responses (native)` to **`Anthropic Messages (routing required)`**.
|
||||
|
||||
|
||||
|
||||
After selecting Anthropic Messages, three supporting fields appear below:
|
||||
|
||||
|
||||
|
||||
- **Auth field**: determines which header carries the API key to the upstream; only one of the two is sent — choose per your gateway's documentation.
|
||||
- `ANTHROPIC_AUTH_TOKEN (Authorization)`: sends `Authorization: Bearer <key>`. This is the default, and most Claude-family relay gateways use it.
|
||||
- `ANTHROPIC_API_KEY (x-api-key)`: sends `x-api-key: <key>`. Some gateways that follow Anthropic's native header convention require this. Picking the wrong one usually shows up as 401 / 403.
|
||||
- **Emulate Claude Code client**: off by default. Turn it on only when the gateway or its upstream restricts usage to "Claude Code only"; when enabled, it spoofs the User-Agent, `anthropic-beta`, and `x-app` headers and injects the Claude Code identity as the first line of the system prompt. Ordinary gateways don't need it; if you're still rejected after enabling it, see "FAQ".
|
||||
- **Max output tokens**: the Anthropic protocol's `max_tokens` is required, and when a Codex request carries no output ceiling the route falls back to a conservative 8192, which may truncate long answers or deep reasoning (showing up as an incomplete reply, `stop_reason=max_tokens`). If you hit truncation, raise this to the model's real ceiling here — but don't exceed it, or the upstream will 400 outright.
|
||||
|
||||
The `Model Mapping` in the same area is optional: add model ids like `claude-opus-4-8`, `claude-sonnet-5`, and `claude-haiku-4-5-20251001` (use the names your upstream recognizes) one per row, and CC Switch generates a model catalog so Codex's `/model` menu can list them; you can also leave it empty, in which case Codex just requests the default model.
|
||||
|
||||
After you save the provider, a `Needs Routing` marker appears on the card — providers like this only work while local routing is running.
|
||||
|
||||
## Step 2: Enable local routing and take over Codex
|
||||
|
||||
Go to the `Routing` page in Settings, expand `Local Routing`, and complete two toggles:
|
||||
|
||||
1. Turn on the `Routing Master Switch` to start the local service (the first time you enable it, an explanatory confirmation dialog appears). The default address is `127.0.0.1:15721`.
|
||||
2. Turn on `Codex` under `Routing Enabled`. If you only want Codex to use routing, you can leave Claude and Gemini off.
|
||||
|
||||
|
||||
|
||||
After takeover, CC Switch points Codex's live config at the local route (`base_url = http://127.0.0.1:15721/v1`), with only a placeholder in `auth.json`. The real Claude key stays in the CC Switch provider config and is injected by the local route on forward, using the auth field you selected.
|
||||
|
||||
## Step 3: Switch providers and restart Codex
|
||||
|
||||
Return to the Codex provider list and click `Enable` on the Claude provider. If routing isn't running, CC Switch shows "This provider uses Anthropic Messages API format, requires the routing service to work properly. Start routing first." — just go back to Step 2 and turn it on.
|
||||
|
||||
After switching, restart the current Codex terminal session: `config.toml` and the model catalog are read when the Codex process starts, and a running process isn't guaranteed to hot-load them.
|
||||
|
||||
Inside Codex you can verify step by step:
|
||||
|
||||
- If you configured model mapping, use `/model` to check whether the Claude models now appear in the menu; without a mapping, Codex just uses the default model.
|
||||
- Send a small question and watch the "Current Provider" on the Settings → Routing page change from "Waiting for first request..." to your Claude provider, with "Total Requests" starting to climb.
|
||||
- In the usage dashboard, these requests show their model names faithfully as `claude-*`, and you can filter by provider to reconcile token usage.
|
||||
|
||||
## Capabilities and known limitations
|
||||
|
||||
- **Prompt caching is automatic**: the conversion bridge injects standard 5-minute prompt-cache markers (system prompt, tool definitions, and conversation history) per Anthropic's convention, so long conversations don't resend everything at full price each turn — no configuration needed.
|
||||
- **Reasoning and tools are lossless**: extended thinking content round-trips across the bridge intact, and multi-turn tool calls, image inputs, and PDF inputs are all fully converted.
|
||||
- **Supports the `[1m]` long-context marker**: when the default model or a model id in the mapping ends with `[1m]` (e.g. `claude-sonnet-5[1m]`), the route strips the marker and automatically adds the corresponding 1M-context beta header, provided the gateway supports that capability.
|
||||
- **Web search is unavailable**: in Anthropic upstream mode, Codex's built-in `web_search` is deliberately disabled — the conversion layer can't translate it for the Anthropic endpoint, and disabling it avoids presenting the model with a tool that's guaranteed to fail.
|
||||
- **Truncation is reported faithfully**: when the upstream stops at the output ceiling or the stream is cut off, Codex sees "incomplete" rather than a disguised success, making it easy to notice and raise the max output tokens.
|
||||
|
||||
## FAQ
|
||||
|
||||
**The upstream returns 401 or 403**
|
||||
|
||||
Nine times out of ten the auth field doesn't match what the gateway wants: switch between `ANTHROPIC_AUTH_TOKEN (Authorization)` and `ANTHROPIC_API_KEY (x-api-key)` per your gateway's documentation and try again (most gateways use the default Bearer). Also confirm the key itself is valid and has balance.
|
||||
|
||||
**Codex reports 404 or cannot find `/responses`**
|
||||
|
||||
Usually Codex routing takeover isn't enabled, or you manually wrote the gateway's address directly into Codex — an Anthropic-protocol upstream has no `/responses` endpoint, so that always 404s. Check whether the current provider's `base_url` in `~/.codex/config.toml` points to `http://127.0.0.1:15721/v1`.
|
||||
|
||||
**The upstream returns 404 (routing already enabled)**
|
||||
|
||||
Check the API Request URL: it should be the gateway's service root, not an address carrying another protocol's path such as `/chat/completions`. When the gateway path is unusual, use the `Full URL` toggle to paste the complete messages endpoint directly.
|
||||
|
||||
**Replies often get cut off mid-way**
|
||||
|
||||
This is the default 8192 output ceiling showing up. Raise it in `Max output tokens` under the provider form's Advanced Options (don't exceed the model's/gateway's real ceiling), save, and retry.
|
||||
|
||||
**`/model` doesn't show the Claude models**
|
||||
|
||||
Confirm you've added entries to the model mapping, then restart Codex after saving the provider — the model catalog isn't hot-loaded by a running process. When the default model isn't in the mapping, the menu won't list it, but a direct request still works.
|
||||
|
||||
**Web search doesn't work**
|
||||
|
||||
By design; see "Capabilities and known limitations". For tasks that need web search, switch back to a Responses/Chat-format provider.
|
||||
|
||||
**An error says usage is restricted to Claude Code**
|
||||
|
||||
Some providers restrict their Claude API to the Claude Code client, so it gets rejected when going through this guide's chain via Codex. Try turning on the `Emulate Claude Code client` toggle in Advanced Options; if it still errors after that, the restriction is enforced on the provider's side — check with your provider whether your key can be used outside Claude Code. Keep this toggle off for ordinary gateways.
|
||||
|
||||
## Compliance note
|
||||
|
||||
Before using this in the "company bans the client but keeps only the gateway" scenario, it's worth confirming that doing so complies with your organization's specific policy — whether what's banned is a specific client or a manner of use differs from one place to the next. When using a third-party relay gateway, read the target gateway's terms on billing, compliance, and data retention.
|
||||
|
||||
## References
|
||||
|
||||
- [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)
|
||||
- [CC Switch v3.17.0 Release Notes](../release-notes/v3.17.0-en.md)
|
||||
- This feature comes from community contribution [#5071](https://github.com/farion1231/cc-switch/pull/5071); thanks @yeeyzy.
|
||||
@@ -0,0 +1,129 @@
|
||||
# Codex で Claude を使う: CC Switch ローカルルーティングガイド
|
||||
|
||||
> 対象バージョン: CC Switch 3.17.0 以降（「Anthropic Messages 上流」は 3.17.0 から導入）。本記事はリポジトリ内のドキュメントとコードをもとに整理し、Claude 系中継ゲートウェイを例に説明します。スクリーンショットは現在のフロントエンド UI から、実際の API Key が漏れないよう匿名化したサンプルデータで生成しています。
|
||||
|
||||
## ローカルルーティングが必要な理由
|
||||
|
||||
新しい Codex CLI は OpenAI Responses API を前提にしています。一方で各種 Claude 系中継ゲートウェイや企業内部ゲートウェイが公開しているのは Anthropic Messages プロトコル、つまり `/v1/messages` です。この 2 つのプロトコルは、リクエストボディ、ストリーミングイベント、レスポンス構造がまったく異なります。この種のゲートウェイのエンドポイントをそのまま Codex 設定に入れても、`/responses` へのリクエストが 404 になるだけです。
|
||||
|
||||
この機能は「手元にあるのが `/v1/messages` エンドポイントだけ」という場面のためのものです。ある Claude 系中継ゲートウェイの Key を持っていて、Codex の操作感で Claude 系モデルを使いたい。あるいは会社がコンプライアンス方針で Claude Code クライアントを禁止し、承認済みの Claude 系ゲートウェイだけを残している——モデル自体は利用できるのに、許可されたクライアントがないだけです。その空白を Codex で埋められます。
|
||||
|
||||
CC Switch では、Codex が常にローカルルートへ接続し、Responses API のままリクエストを送るようにします。ルートは現在のプロバイダーが Anthropic 形式だと判定すると、リクエストを Anthropic Messages に変換して上流へ送り、最後にレスポンスを Responses 形式へ戻して Codex に返します。
|
||||
|
||||
|
||||
|
||||
この経路は主に 4 つのステップに分かれます：
|
||||
|
||||
1. Codex を引き継ぐと、ローカル設定は `http://127.0.0.1:15721/v1` に書き換えられ、`wire_api = "responses"` が強制的に維持されます。
|
||||
2. プロバイダーの上流フォーマット `anthropic` が、実際の上流は Anthropic Messages プロトコルだとルートに伝えます。
|
||||
3. ルートは `/responses` を `/v1/messages` に書き換え、Responses のリクエストボディを Anthropic のリクエストボディへ変換します。
|
||||
4. 上流から返ってきた後、ルートは Anthropic の JSON または SSE を Codex が理解できる Responses JSON/SSE へ変換して返します——推論内容、ツール呼び出し、画像もすべて変換対象です。
|
||||
|
||||
## 事前準備
|
||||
|
||||
先に次の 3 つを用意してください：
|
||||
|
||||
- インストール済みで起動できる CC Switch（3.17.0 以降）。
|
||||
- インストール済みの Codex CLI。少なくとも 1 回は実行し、`~/.codex/` のディレクトリ構造が存在していること。
|
||||
- Anthropic Messages プロトコルのエンドポイント（`/v1/messages`）へアクセスできる API Key——ある Claude 系中継ゲートウェイ、または企業内部の Claude ゲートウェイのもの。エンドポイントと認証方式はゲートウェイのドキュメントに従ってください。注意：一部のプロバイダーは Claude API を Claude Code 内でのみ利用できるよう制限しており、この種の Key を Codex で使うとエラーになることがあります。判断がつかない場合は、先にプロバイダーへ問い合わせてください。
|
||||
|
||||
Codex タブには現時点で Anthropic の内蔵プリセットがないため、以下では「カスタム設定」の手順で進めます。入力する項目は全体でも 4〜5 個です。
|
||||
|
||||
## Step 1: Codex プロバイダーを追加する
|
||||
|
||||
CC Switch を開き、上部の `Codex` タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。デフォルトの `カスタム設定` のまま、次の項目を入力します：
|
||||
|
||||
- **プロバイダー名**: 任意です。たとえば `Claude Gateway`。
|
||||
- **API Key**: あなたのゲートウェイの Key。実際の Key は CC Switch 内にのみ保存され、ローカルルートが転送時に注入するため、Codex の live 設定には入りません。
|
||||
- **API エンドポイント**: ゲートウェイのルートアドレスを入力すれば十分です。たとえば `https://claude-gateway.example.com`。`/v1` は付けても付けなくても正しく処理され、ルートが自動的に `/v1/messages` へリクエストを送ります。自分で `/v1/messages` を組み立てないでください（ゲートウェイのドキュメントが完全な messages URL を指定している場合は、隣の `フル URL` スイッチをオンにしてそのまま貼り付けても構いません）。アドレス欄の下に表示される「OpenAI Response 互換」という黄色のヒントは Responses 直結向けの汎用文言です。Anthropic フォーマットを選ぶ場合は本記事のとおりに入力してください。
|
||||
- **デフォルトモデル**: ゲートウェイが認識する Claude モデル ID を入力します。たとえば `claude-sonnet-5`。ゲートウェイのドキュメントにあるモデル名に従ってください。
|
||||
|
||||
続いて `高級オプション` を展開し、`上流フォーマット` をデフォルトの `Responses（ネイティブ）` から **`Anthropic Messages（ルーティング必須）`** に変更します。
|
||||
|
||||
|
||||
|
||||
Anthropic Messages を選ぶと、下に 3 つの関連フィールドが追加で表示されます：
|
||||
|
||||
|
||||
|
||||
- **認証フィールド**: API Key をどのヘッダーで上流へ送るかを決めます。送信されるのはどちらか一方のみで、ゲートウェイのドキュメントに従って選びます。
|
||||
- `ANTHROPIC_AUTH_TOKEN（Authorization）`: `Authorization: Bearer <key>` を送信します。デフォルト値で、多くの Claude 系中継ゲートウェイがこの方式を使います。
|
||||
- `ANTHROPIC_API_KEY（x-api-key）`: `x-api-key: <key>` を送信します。Anthropic ネイティブのヘッダー規約を踏襲する一部のゲートウェイはこちらを要求します。選択を誤ると、通常 401 / 403 という形で現れます。
|
||||
- **Claude Code クライアントを模倣**: デフォルトはオフです。ゲートウェイ（またはその上流）が「Claude Code からのみ利用可能」と制限している場合にのみオンにします。オンにすると User-Agent・`anthropic-beta`・`x-app` ヘッダーを偽装し、システムプロンプトの先頭行に Claude Code のアイデンティティを注入します。通常のゲートウェイでは不要です。オンにしても拒否される場合の対処は「よくある質問」を参照してください。
|
||||
- **最大出力トークン**: Anthropic プロトコルの `max_tokens` は必須項目です。Codex のリクエストが出力上限を含まない場合、ルートは保守的に 8192 で補います。長い回答や深い思考では切り詰められることがあります（回答が不完全になる、`stop_reason=max_tokens` になる、といった形で現れます）。切り詰められたら、ここでモデルの実際の上限に合わせて引き上げてください。ただし超えないように——超えると上流が直接 400 を返します。
|
||||
|
||||
同じエリアの `モデルマッピング` は任意です。`claude-opus-4-8`、`claude-sonnet-5`、`claude-haiku-4-5-20251001` のようなモデル ID（上流が認識する名前に従ってください）を 1 行ずつ追加すると、CC Switch がモデルカタログを生成し、Codex の `/model` メニューに一覧表示できるようになります。入力しなくても利用でき、その場合 Codex はデフォルトモデルを直接リクエストします。
|
||||
|
||||
プロバイダーを保存すると、カードに `ルーティングが必要` のマークが表示されます——この種のプロバイダーは、ローカルルーティングが実行中でなければ正しく動作しません。
|
||||
|
||||
## Step 2: ローカルルーティングを有効にして Codex をルーティングする
|
||||
|
||||
設定の `ルーティング` ページに入り、`ローカルルーティング` を展開して、2 つのスイッチを設定します：
|
||||
|
||||
1. `ルーティング総スイッチ` をオンにしてローカルサービスを起動します（初回起動時は説明の確認ダイアログが表示されます）。デフォルトアドレスは `127.0.0.1:15721` です。
|
||||
2. `ルーティング有効` で `Codex` をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。
|
||||
|
||||
|
||||
|
||||
引き継ぎ後、CC Switch は Codex の live 設定をローカルルートへ向け（`base_url = http://127.0.0.1:15721/v1`）、`auth.json` にはプレースホルダーだけが入ります。実際の Claude Key は CC Switch のプロバイダー設定内に残り、ローカルルートが転送時に、あなたが選んだ認証フィールドに従って注入します。
|
||||
|
||||
## Step 3: プロバイダーを切り替えて Codex を再起動する
|
||||
|
||||
Codex プロバイダー一覧に戻り、Claude プロバイダーの `有効化` をクリックします。ルーティングが実行されていない場合、CC Switch は「このプロバイダーは Anthropic Messages API フォーマットを使用しており、ルーティングサービスが必要です。先にルーティングを起動してください」と表示します——Step 2 に戻ってオンにすれば解決します。
|
||||
|
||||
切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。`config.toml` とモデルカタログは Codex プロセスの起動時に読み込まれるため、実行中のプロセスがホットロードするとは限りません。
|
||||
|
||||
Codex に入ったら、段階的に確認できます：
|
||||
|
||||
- モデルマッピングを設定している場合は、`/model` で Claude モデルがメニューに表示されているか確認します。マッピングを設定していない場合、Codex はデフォルトモデルを直接使います。
|
||||
- 小さな質問を 1 つ送り、設定 → ルーティングページの「現在のプロバイダー」が「最初のリクエスト待ち」からあなたの Claude プロバイダーに変わり、「総リクエスト数」が増え始めるのを確認します。
|
||||
- 使用量ダッシュボードでは、これらのリクエストのモデル名が `claude-*` としてそのまま表示され、プロバイダーで絞り込んで token 使用量を照合できます。
|
||||
|
||||
## 機能の範囲と既知の制限
|
||||
|
||||
- **プロンプトキャッシュが自動で有効**: 変換ブリッジは Anthropic 標準に従って 5 分のプロンプトキャッシュマーカー（システムプロンプト、ツール定義、対話履歴）を注入します。長い対話でも毎回全額で再送されることはなく、設定は不要です。
|
||||
- **推論とツールを無損失で往復**: extended thinking の内容はブリッジをまたいで往復しても保持され、複数ターンのツール呼び出し、画像、PDF 入力も完全に変換されます。
|
||||
- **`[1m]` 長コンテキストマーカーに対応**: デフォルトモデルやモデルマッピングのモデル ID が `[1m]` で終わる場合（例：`claude-sonnet-5[1m]`）、ルートはマーカーを取り除き、対応する 1M コンテキストの beta ヘッダーを自動で補います。ただし、ゲートウェイがその機能に対応していることが前提です。
|
||||
- **Web 検索は利用不可**: Anthropic 上流モードでは Codex の内蔵 `web_search` が意図的に無効化されます——変換層が Anthropic エンドポイントへ翻訳できないためで、必ず失敗するツールをモデルに提示しないための措置です。
|
||||
- **切り詰めをそのまま報告**: 上流が出力上限で止まったりストリームが切断されたりすると、Codex は偽装された成功ではなく「未完了」を受け取ります。これにより気づきやすくなり、最大出力トークンを引き上げる判断ができます。
|
||||
|
||||
## よくある質問
|
||||
|
||||
**上流が 401 または 403 を返す**
|
||||
|
||||
ほとんどの場合、認証フィールドがゲートウェイの要求と一致していません。`ANTHROPIC_AUTH_TOKEN（Authorization）` と `ANTHROPIC_API_KEY（x-api-key）` を、ゲートウェイのドキュメントに従って切り替えて再試行してください（多くのゲートウェイはデフォルトの Bearer です）。あわせて、Key 自体が有効で残高があることも確認してください。
|
||||
|
||||
**Codex が 404 を返す、または `/responses` が見つからない**
|
||||
|
||||
多くの場合、Codex のルーティング引き継ぎが有効になっていないか、ゲートウェイのエンドポイントを手動で Codex に直接書いています——Anthropic プロトコルの上流には `/responses` エンドポイントが存在しないため、必ず 404 になります。`~/.codex/config.toml` の現在の provider の `base_url` が `http://127.0.0.1:15721/v1` を指しているか確認してください。
|
||||
|
||||
**上流が 404 を返す（ルーティングは有効）**
|
||||
|
||||
API エンドポイントを確認してください。ゲートウェイのルートアドレスであるべきで、`/chat/completions` のような別プロトコルのパスが付いたアドレスではいけません。ゲートウェイのパスが特殊な場合は、`フル URL` スイッチを使って完全な messages エンドポイントをそのまま貼り付けてください。
|
||||
|
||||
**回答が途中で切り詰められることが多い**
|
||||
|
||||
これはデフォルトの 8192 出力上限の現れです。プロバイダーフォームの高級オプションにある `最大出力トークン` で引き上げ（モデル / ゲートウェイの実際の上限を超えないように）、保存してから再試行してください。
|
||||
|
||||
**`/model` に Claude モデルが表示されない**
|
||||
|
||||
モデルマッピングにエントリが追加されていることを確認し、プロバイダーを保存してから Codex を再起動してください——モデルカタログは実行中のプロセスにはホットロードされません。デフォルトモデルがマッピングに含まれていない場合、メニューには表示されませんが、直接リクエストは有効です。
|
||||
|
||||
**Web 検索が使えない**
|
||||
|
||||
仕様どおりです。「機能の範囲と既知の制限」を参照してください。Web 検索が必要なタスクは、Responses / Chat フォーマットのプロバイダーへ切り替えることをおすすめします。
|
||||
|
||||
**Claude Code でしか使えないというエラーが出る**
|
||||
|
||||
一部のプロバイダーは、その Claude API を Claude Code クライアント内でのみ利用できるよう制限しており、本ガイドの経路で Codex から使うと拒否されます。高級オプションの `Claude Code クライアントを模倣` スイッチをオンにして試すことはできますが、それでもエラーになる場合、制限はプロバイダーのサーバー側にあります。その Key を Claude Code 以外で使えるかどうか、プロバイダーへ問い合わせて確認してください。通常のゲートウェイでは、このスイッチはオフのままにしてください。
|
||||
|
||||
## コンプライアンスに関する注意
|
||||
|
||||
「会社がクライアントを禁止し、ゲートウェイだけを残している」という場面で使う前に、この使い方が所属組織の具体的な方針に沿っているかを確認することをおすすめします——禁止されているのが特定のクライアントなのか、それともある種の利用方法なのかは、組織によって解釈が異なります。サードパーティ中継ゲートウェイを使う場合は、対象ゲートウェイの課金・コンプライアンス・データ保持に関する規約を必ずお読みください。
|
||||
|
||||
## 参考リンク
|
||||
|
||||
- [CC Switch ユーザーマニュアル: プロキシサービス](../user-manual/ja/4-proxy/4.1-service.md)
|
||||
- [CC Switch ユーザーマニュアル: アプリケーションルーティング](../user-manual/ja/4-proxy/4.2-routing.md)
|
||||
- [CC Switch v3.17.0 リリースノート](../release-notes/v3.17.0-ja.md)
|
||||
- この機能はコミュニティからの貢献 [#5071](https://github.com/farion1231/cc-switch/pull/5071) によるものです。@yeeyzy に感謝します。
|
||||
@@ -0,0 +1,129 @@
|
||||
# 在 Codex 中用 Claude：CC Switch 本地路由攻略
|
||||
|
||||
> 适用版本：CC Switch 3.17.0 及以上（「Anthropic Messages 上游」自 3.17.0 引入）。本文根据仓库内文档与代码整理，以 Claude 系中转网关为例演示。截图来自当前前端界面，使用去敏示例数据生成，避免泄露真实 API Key。
|
||||
|
||||
## 为什么需要本地路由
|
||||
|
||||
新版 Codex CLI 面向的是 OpenAI Responses API，而各类 Claude 系中转网关、企业内部网关暴露的是 Anthropic Messages 协议，也就是 `/v1/messages`。这两种协议的请求体、流式事件和返回结构完全不同，把这类网关的接口地址直接填进 Codex 配置里，结果只能是请求 `/responses` 返回 404。
|
||||
|
||||
这个功能面向的就是「手里只有 `/v1/messages` 端点」的场景：你有某个 Claude 系中转网关的 Key，想用 Codex 的交互习惯跑 Claude 系列模型；或者公司出于合规策略禁用了 Claude Code 客户端、只保留了经批准的 Claude 系网关——模型本身可用，缺的只是一个被允许的客户端，现在 Codex 可以补上这个位置。
|
||||
|
||||
CC Switch 的做法是让 Codex 始终连本机路由，仍以 Responses API 发送请求；路由识别当前供应商是 Anthropic 格式后，把请求转换成 Anthropic Messages 发给上游，再把响应转换回 Responses 形态返回给 Codex。
|
||||
|
||||
|
||||
|
||||
这条链路主要分成四步：
|
||||
|
||||
1. Codex 接管时，本地配置会被写成 `http://127.0.0.1:15721/v1`，并强制保持 `wire_api = "responses"`。
|
||||
2. 供应商的上游格式 `anthropic` 会告诉路由：真实上游说的是 Anthropic Messages 协议。
|
||||
3. 路由把 `/responses` 改写到 `/v1/messages`，并把 Responses 请求体转换成 Anthropic 请求体。
|
||||
4. 上游返回后，路由再把 Anthropic 的 JSON 或 SSE 转回 Codex 能理解的 Responses JSON/SSE——推理内容、工具调用、图片都在转换范围内。
|
||||
|
||||
## 准备工作
|
||||
|
||||
你需要先准备好三样东西：
|
||||
|
||||
- 已安装并能启动的 CC Switch（3.17.0 及以上）。
|
||||
- 已安装 Codex CLI，并至少运行过一次，让 `~/.codex/` 目录结构存在。
|
||||
- 一个能访问 Anthropic Messages 协议端点（`/v1/messages`）的 API Key——来自某个 Claude 系中转网关，或企业内部的 Claude 网关；端点地址和认证方式以网关文档为准。注意：部分供应商会限制其 Claude API 只能在 Claude Code 中使用，这类 Key 走 Codex 可能会报错，拿不准就先咨询供应商。
|
||||
|
||||
Codex 页签目前没有 Anthropic 内置预设，下面走「自定义配置」路径，全程也就四五个字段。
|
||||
|
||||
## 第一步：添加 Codex 供应商
|
||||
|
||||
打开 CC Switch，切到顶部的 `Codex` 标签，点击右上角的加号添加供应商，保持默认的 `自定义配置`，然后填写：
|
||||
|
||||
- **供应商名称**：随意，例如 `Claude Gateway`。
|
||||
- **API Key**：你的网关 Key。真实 Key 只保存在 CC Switch 里，由本地路由转发时注入，不会进入 Codex 的 live 配置。
|
||||
- **API 请求地址**：填网关服务根地址即可，例如 `https://claude-gateway.example.com`。带不带 `/v1` 都能被正确处理，路由会自动把请求打到 `/v1/messages`；不要自己拼 `/v1/messages`（如果网关文档给的就是完整 messages URL，打开旁边的 `完整 URL` 开关原样粘贴也可以）。地址栏下方那句「兼容 OpenAI Response 格式」的黄色提示是为 Responses 直连场景写的通用文案，选 Anthropic 格式时按本文填写即可。
|
||||
- **默认模型**：填网关认识的 Claude 模型 id，例如 `claude-sonnet-5`，以网关文档给出的模型名为准。
|
||||
|
||||
然后展开 `高级选项`，把 `上游格式` 从默认的 `Responses（原生）` 改成 **`Anthropic Messages（需开启路由）`**。
|
||||
|
||||
|
||||
|
||||
选中 Anthropic Messages 后，下方会多出三个配套字段：
|
||||
|
||||
|
||||
|
||||
- **认证字段**：决定 API Key 以哪个请求头发给上游，两者只发其一，按网关文档选择。
|
||||
- `ANTHROPIC_AUTH_TOKEN（Authorization）`：发 `Authorization: Bearer <key>`，是默认值，多数 Claude 系中转网关用这种。
|
||||
- `ANTHROPIC_API_KEY（x-api-key）`：发 `x-api-key: <key>`，部分沿用 Anthropic 原生请求头约定的网关要求这种。选错通常表现为 401 / 403。
|
||||
- **模拟 Claude Code 客户端**：默认关闭。仅当网关或其上游限制「只能通过 Claude Code 使用」时才打开，开启后会伪装 User-Agent、`anthropic-beta`、`x-app` 请求头，并在系统提示首行注入 Claude Code 身份。普通网关不需要开；开启后仍被拒的处理见「常见问题」。
|
||||
- **最大输出 tokens**：Anthropic 协议的 `max_tokens` 是必填项，而 Codex 请求未携带输出上限时，路由按保守的 8192 兜底，长回答或深度思考可能被截断（表现为回复不完整、`stop_reason=max_tokens`）。遇到截断就在这里按模型真实上限调高，但不要超过——超了上游会直接 400。
|
||||
|
||||
同区的 `模型映射` 是可选项：把 `claude-opus-4-8`、`claude-sonnet-5`、`claude-haiku-4-5-20251001` 这类模型 id（以你上游认识的名字为准）逐行加进去，CC Switch 会生成模型目录让 Codex 的 `/model` 菜单能列出它们；不填也能用，Codex 会直接请求默认模型。
|
||||
|
||||
保存供应商后，卡片上会出现 `需要路由` 标记——这类供应商必须在本地路由运行时才能正常工作。
|
||||
|
||||
## 第二步：开启本地路由并接管 Codex
|
||||
|
||||
进入设置里的 `路由` 页面，展开 `本地路由`，完成两个开关：
|
||||
|
||||
1. 打开 `路由总开关`，启动本地服务（首次开启会弹出一个说明确认框）。默认地址是 `127.0.0.1:15721`。
|
||||
2. 在 `路由启用` 中打开 `Codex`。如果只想让 Codex 走路由，可以保持 Claude、Gemini 关闭。
|
||||
|
||||
|
||||
|
||||
接管后，CC Switch 会把 Codex 的 live 配置指向本机路由（`base_url = http://127.0.0.1:15721/v1`），`auth.json` 里只有占位符。真实 Claude Key 仍保存在 CC Switch 的供应商配置里，由本地路由在转发时按你选的认证字段注入。
|
||||
|
||||
## 第三步：切换供应商并重启 Codex
|
||||
|
||||
回到 Codex 供应商列表，点击 Claude 供应商的 `启用`。如果路由没有在运行，CC Switch 会提示「此供应商使用 Anthropic Messages 接口格式，需要路由服务才能正常使用，请先启动路由」——回到第二步打开即可。
|
||||
|
||||
切换后建议重启当前 Codex 终端会话：`config.toml` 和模型目录是 Codex 进程启动时读取的，运行中的进程不保证热加载。
|
||||
|
||||
进入 Codex 后可以逐级验证：
|
||||
|
||||
- 配置了模型映射的话，用 `/model` 查看 Claude 模型是否已出现在菜单里；没配映射时 Codex 直接用默认模型。
|
||||
- 发一个小问题，观察设置 → 路由页面的「当前 Provider」从「等待首次请求」变成你的 Claude 供应商、「总请求数」开始增长。
|
||||
- 用量看板里，这些请求的模型名会如实显示为 `claude-*`，可按供应商筛选核对 token 用量。
|
||||
|
||||
## 能力边界与已知限制
|
||||
|
||||
- **提示缓存自动生效**：转换桥会按 Anthropic 标准注入 5 分钟提示缓存标记（系统提示、工具定义与对话历史），长对话不会每轮全价重发，无需任何配置。
|
||||
- **推理与工具无损**：extended thinking 内容跨桥往返保留，多轮工具调用、图片与 PDF 输入都被完整转换。
|
||||
- **支持 `[1m]` 长上下文标记**：默认模型或模型映射里的模型 id 以 `[1m]` 结尾（如 `claude-sonnet-5[1m]`）时，路由会剥掉标记并自动补发对应的 1M 上下文 beta 头，前提是网关支持该能力。
|
||||
- **联网搜索不可用**：Anthropic 上游模式下 Codex 的内置 `web_search` 会被主动禁用——转换层无法把它翻译给 Anthropic 端点，禁用是为了不给模型呈现一个必然失败的工具。
|
||||
- **截断如实上报**：上游停在输出上限或流被掐断时，Codex 会看到「未完成」而不是被伪装的成功，方便你察觉并调高最大输出 tokens。
|
||||
|
||||
## 常见问题
|
||||
|
||||
**上游返回 401 或 403**
|
||||
|
||||
十有八九是认证字段与网关要求不符：在 `ANTHROPIC_AUTH_TOKEN（Authorization）` 与 `ANTHROPIC_API_KEY（x-api-key）` 之间按网关文档换一个再试（多数网关用默认的 Bearer）。另外确认 Key 本身有效、有余额。
|
||||
|
||||
**Codex 报 404 或找不到 `/responses`**
|
||||
|
||||
通常是没有开启 Codex 路由接管，或者你手动把网关的地址直接写给了 Codex——Anthropic 协议的上游没有 `/responses` 端点，这样一定 404。检查 `~/.codex/config.toml` 里当前 provider 的 `base_url` 是否指向 `http://127.0.0.1:15721/v1`。
|
||||
|
||||
**上游返回 404（路由已开启）**
|
||||
|
||||
检查 API 请求地址：应该是网关的服务根地址，而不是带 `/chat/completions` 之类其它协议路径的地址。网关路径特殊时，用 `完整 URL` 开关直接粘贴完整的 messages 端点。
|
||||
|
||||
**回复经常中途截断**
|
||||
|
||||
这是默认 8192 输出上限的表现。在供应商表单高级选项的 `最大输出 tokens` 里调高（不要超过模型/网关真实上限），保存后重试。
|
||||
|
||||
**`/model` 看不到 Claude 模型**
|
||||
|
||||
确认模型映射里已添加条目，保存供应商后重启 Codex——模型目录不会被运行中的进程热加载。默认模型不在映射里时菜单不会列出它，但直接请求仍然有效。
|
||||
|
||||
**联网搜索用不了**
|
||||
|
||||
设计如此，见「能力边界」。需要联网搜索的任务建议切回 Responses/Chat 格式的供应商。
|
||||
|
||||
**报错提示只能在 Claude Code 中使用**
|
||||
|
||||
部分供应商会限制其 Claude API 只能在 Claude Code 客户端中使用，经 Codex 走本攻略的链路时会被拒绝。可以尝试打开高级选项里的 `模拟 Claude Code 客户端` 开关；若开启后仍然报错，说明限制在供应商服务端，请咨询供应商确认你的 Key 能否在 Claude Code 之外使用。普通网关请保持该开关关闭。
|
||||
|
||||
## 合规提示
|
||||
|
||||
在「公司禁客户端、只留网关」的场景下使用前，建议确认这样做符合你所在组织的具体政策——被禁的是特定客户端还是某种使用方式，各家口径不同。使用第三方中转网关时，请阅读目标网关关于计费、合规与数据留存的条款。
|
||||
|
||||
## 参考链接
|
||||
|
||||
- [CC Switch 用户手册：代理服务](../user-manual/zh/4-proxy/4.1-service.md)
|
||||
- [CC Switch 用户手册：应用路由](../user-manual/zh/4-proxy/4.2-routing.md)
|
||||
- [CC Switch v3.17.0 发布说明](../release-notes/v3.17.0-zh.md)
|
||||
- 功能来自社区贡献 [#5071](https://github.com/farion1231/cc-switch/pull/5071)，感谢 @yeeyzy
|
||||
Reference in New Issue
Block a user