ゲートウェイの互換性要件

Codex のゲートウェイは、ここで説明する Responses API の動作を維持する必要があります。 対象は、エンドポイント、ストリーミング、会話の継続、ツール呼び出し、認証、ルーティング、 有用なエラーです。

リクエストとエンドポイント

wire_api = "responses" を使ってゲートウェイプロバイダーを設定します。ベース URL が https://gateway.example.com/v1 のような場合、ゲートウェイは POST /v1/responses を受け付け、クライアントが使用するリクエストとレスポンスのフィールドを維持する必要があります。 Chat Completions または Anthropic Messages のエンドポイントが動作しても、 Responses との互換性があるとは判断できません。

ヘルスエンドポイントとモデル一覧エンドポイントは、任意の運用補助機能です。これらでは Codex の会話を実行しないため、ツールのサポートを証明できません。

ストリーミング

回答全体をバッファリングせず、server-sent events（SSE）を逐次転送します。イベントの種類とペイロードを維持し、正常終了を示す終端の response.completed イベントも維持してください。クライアントがレスポンスの失敗と接続の停止を区別できるよう、エラーイベントと失敗イベントを転送します。

ゲートウェイだけでなく、ロードバランサーとリバースプロキシを経由するストリーム全体を検証してください。ストリームが完了しないテキスト応答だけでは不十分です。

会話の継続

後続ターンで再送される会話の入力を維持します。ゲートウェイは、 次のターンに必要な過去のメッセージ、ツール呼び出し、ツールの結果を受け付ける必要があります。

WebSocket または差分転送を有効にする場合は、その previous_response_id の動作も検証してください。ステートレスな HTTP Responses の経路では、 その継続の仕組みを必要とせずに、再送された入力を使用できます。

ツール

関数呼び出し項目と、それに対応する function_call_output 項目を、 呼び出しと結果を関連付ける識別子も含めて維持します。ループ全体が動作する必要があります。Codex が呼び出しを受信し、ツールを実行して、その結果を送信し、 最終回答を受け取るまでを確認してください。

テキストリクエストの成功だけでは、このループを検証できません。有効にする予定の実際のモデルとクライアント機能をテストしてください。ゲートウェイがリクエストフィールドを受け付けても、 上流モデルが対応する機能を実装している証拠にはなりません。

認証とヘッダー

展開時に選択したクライアント認証の仕組みをサポートします。 env_key またはコマンドによる bearer トークン、カスタムヘッダーで送信する認証情報には env_http_headers を使用します。 シークレットを含むヘッダー値には環境変数を使用し、 設定に直接埋め込まないでください。設定と認証情報ヘルパーの仕様については、 カスタムプロバイダーのリファレンス を参照してください。

開発者は、ゲートウェイの上流プロバイダーの ID とは別に認証します。 管理者キーと上流の認証情報はゲートウェイ側に保持してください。ルーティングとユーザーの識別に必要なヘッダーを維持し、認証情報の有効期限、 更新、取り消しをテストします。

モデルのルーティングとメタデータ

各 Codex 向けモデル名は、意図した上流モデルにルーティングされる必要があります。 モデルの自己申告に頼らず、ゲートウェイの記録でルーティングを検証してください。

展開した Codex バージョンが認識する名前を使用するか、 カスタムエイリアスに対応するカタログを提供します。 モデルの利用可否と移行メタデータも確認してください。置き換え先のモデルも必ずゲートウェイ経由でルーティングされる必要があります。移行を伴わない組織独自のエイリアスでは、 カタログエントリの upgrade を null に設定します。カタログのメタデータはクライアントの動作に使われますが、 モデルに機能を追加したり、 ゲートウェイのルートを作成したりするものではありません。コンテキストの上限、推論オプション、ツールを実際の上流モデルとプロバイダーに照らして検証してください。汎用のゲートウェイ接続には、 Codex の組み込みプロバイダー連携で行われるメタデータの調整は自動的には適用されません。

認識されるモデル名

展開した Codex バージョンが認識する正確なモデル名を、ゲートウェイのエイリアスと Codex の model に使用します。上流プロバイダーがそのモデルをサポートしており、 組織がその使用を承認していることを確認してください。

codex --version を確認し、Codex モデルカタログで対応する rust-v<version> タグを選択します。 カスタムビルドではそのソースコミットを使用し、デスクトップへの展開では同梱の CLI バージョンに合わせます。エントリの slug の値を確認して、そのバージョンが認識する名前を調べてください。ゲートウェイがモデルの機能を変更する場合は、 認識される名前であっても、その違いを反映したカタログのメタデータを提供します。

エラー

クライアント認証エラー、不明なモデルのルート、 レート制限、上流での障害を有用な形で区別できるようにします。すべての失敗を汎用的な 500 レスポンスにまとめないでください。トークン、プロバイダーの認証情報、機密性の高いリクエスト内容を公開せずに、障害が発生したレイヤーを診断するために十分な情報を返します。

データとツールの境界

モデルのトラフィックは、次の経路を通ります。

Codex client -> LLM gateway -> model provider

クライアントは開発者の認証情報を使ってゲートウェイに対して認証します。ゲートウェイは上流プロバイダーの認証情報を使ってモデルにアクセスします。モデルリクエストに含まれるプロンプト、ソースの抜粋、ツールの引数、ツールの結果は、 ゲートウェイを通過する可能性があります。これに応じて、ログ記録、保持、秘匿化、アクセス、エクスポートの制御を設定してください。

モデルゲートウェイは、Codex が行うすべての接続をルーティングするわけではありません。ローカルコマンドはクライアントの実行環境で実行されます。MCP server、プラグインサービス、ブラウザーやアプリの操作、その他の有効なサービスは、別々のネットワーク経路と認証情報を使用する場合があります。モデルプロバイダーの設定は、それらの権限を付与したり、 ネットワーク制御を置き換えたりするものではありません。これらの境界については、エージェントの承認とセキュリティ および MCP を参照してください。

適合性のチェックリスト

展開するクライアント、ゲートウェイ、モデルの組み合わせごとに、次の証拠を記録します。

• Responses のリクエストとレスポンスのフィールド。
• SSE の逐次配信と正常な終端完了。
• 再送された入力を使った後続ターン。
• 選択した転送方式で使用する場合の previous_response_id。
• 関数呼び出し、対応する結果、最終回答。
• 正しいモデルのルーティングと、一致するメタデータ。
• ユーザーごとの識別、認証情報の更新、取り消し。
• 有用な認証、ルーティング、レート制限、上流のエラー。
• 機密情報を秘匿化した診断情報と、意図したログ記録ポリシー。

展開時のテスト手順を使い、 設定を配布する前にこれらの証拠を収集してください。