docs/guides/codex-claude-routing-guide-ja.md
対象バージョン: 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 つのステップに分かれます：
http://127.0.0.1:15721/v1 に書き換えられ、wire_api = "responses" が強制的に維持されます。anthropic が、実際の上流は Anthropic Messages プロトコルだとルートに伝えます。/responses を /v1/messages に書き換え、Responses のリクエストボディを Anthropic のリクエストボディへ変換します。先に次の 3 つを用意してください：
~/.codex/ のディレクトリ構造が存在していること。/v1/messages）へアクセスできる API Key——ある Claude 系中継ゲートウェイ、または企業内部の Claude ゲートウェイのもの。エンドポイントと認証方式はゲートウェイのドキュメントに従ってください。注意：一部のプロバイダーは Claude API を Claude Code 内でのみ利用できるよう制限しており、この種の Key を Codex で使うとエラーになることがあります。判断がつかない場合は、先にプロバイダーへ問い合わせてください。Codex タブには現時点で Anthropic の内蔵プリセットがないため、以下では「カスタム設定」の手順で進めます。入力する項目は全体でも 4〜5 個です。
CC Switch を開き、上部の Codex タブへ切り替え、右上のプラスボタンからプロバイダーを追加します。デフォルトの カスタム設定 のまま、次の項目を入力します：
Claude Gateway。https://claude-gateway.example.com。/v1 は付けても付けなくても正しく処理され、ルートが自動的に /v1/messages へリクエストを送ります。自分で /v1/messages を組み立てないでください（ゲートウェイのドキュメントが完全な messages URL を指定している場合は、隣の フル URL スイッチをオンにしてそのまま貼り付けても構いません）。アドレス欄の下に表示される「OpenAI Response 互換」という黄色のヒントは Responses 直結向けの汎用文言です。Anthropic フォーマットを選ぶ場合は本記事のとおりに入力してください。claude-sonnet-5。ゲートウェイのドキュメントにあるモデル名に従ってください。続いて 高級オプション を展開し、上流フォーマット をデフォルトの Responses（ネイティブ） から Anthropic Messages（ルーティング必須） に変更します。
Anthropic Messages を選ぶと、下に 3 つの関連フィールドが追加で表示されます：
ANTHROPIC_AUTH_TOKEN（Authorization）: Authorization: Bearer <key> を送信します。デフォルト値で、多くの Claude 系中継ゲートウェイがこの方式を使います。ANTHROPIC_API_KEY（x-api-key）: x-api-key: <key> を送信します。Anthropic ネイティブのヘッダー規約を踏襲する一部のゲートウェイはこちらを要求します。選択を誤ると、通常 401 / 403 という形で現れます。anthropic-beta・x-app ヘッダーを偽装し、システムプロンプトの先頭行に Claude Code のアイデンティティを注入します。通常のゲートウェイでは不要です。オンにしても拒否される場合の対処は「よくある質問」を参照してください。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 はデフォルトモデルを直接リクエストします。
プロバイダーを保存すると、カードに ルーティングが必要 のマークが表示されます——この種のプロバイダーは、ローカルルーティングが実行中でなければ正しく動作しません。
設定の ルーティング ページに入り、ローカルルーティング を展開して、2 つのスイッチを設定します：
ルーティング総スイッチ をオンにしてローカルサービスを起動します（初回起動時は説明の確認ダイアログが表示されます）。デフォルトアドレスは 127.0.0.1:15721 です。ルーティング有効 で Codex をオンにします。Codex だけをルーティングしたい場合は、Claude と Gemini はオフのままで構いません。引き継ぎ後、CC Switch は Codex の live 設定をローカルルートへ向け（base_url = http://127.0.0.1:15721/v1）、auth.json にはプレースホルダーだけが入ります。実際の Claude Key は CC Switch のプロバイダー設定内に残り、ローカルルートが転送時に、あなたが選んだ認証フィールドに従って注入します。
Codex プロバイダー一覧に戻り、Claude プロバイダーの 有効化 をクリックします。ルーティングが実行されていない場合、CC Switch は「このプロバイダーは Anthropic Messages API フォーマットを使用しており、ルーティングサービスが必要です。先にルーティングを起動してください」と表示します——Step 2 に戻ってオンにすれば解決します。
切り替え後は、現在の Codex ターミナルセッションを再起動することをおすすめします。config.toml とモデルカタログは Codex プロセスの起動時に読み込まれるため、実行中のプロセスがホットロードするとは限りません。
Codex に入ったら、段階的に確認できます：
/model で Claude モデルがメニューに表示されているか確認します。マッピングを設定していない場合、Codex はデフォルトモデルを直接使います。claude-* としてそのまま表示され、プロバイダーで絞り込んで token 使用量を照合できます。[1m] 長コンテキストマーカーに対応: デフォルトモデルやモデルマッピングのモデル ID が [1m] で終わる場合（例：claude-sonnet-5[1m]）、ルートはマーカーを取り除き、対応する 1M コンテキストの beta ヘッダーを自動で補います。ただし、ゲートウェイがその機能に対応していることが前提です。web_search が意図的に無効化されます——変換層が Anthropic エンドポイントへ翻訳できないためで、必ず失敗するツールをモデルに提示しないための措置です。上流が 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 以外で使えるかどうか、プロバイダーへ問い合わせて確認してください。通常のゲートウェイでは、このスイッチはオフのままにしてください。
「会社がクライアントを禁止し、ゲートウェイだけを残している」という場面で使う前に、この使い方が所属組織の具体的な方針に沿っているかを確認することをおすすめします——禁止されているのが特定のクライアントなのか、それともある種の利用方法なのかは、組織によって解釈が異なります。サードパーティ中継ゲートウェイを使う場合は、対象ゲートウェイの課金・コンプライアンス・データ保持に関する規約を必ずお読みください。