ゲートウェイを展開する
組織向けの Codex ゲートウェイ接続を配布し、検証します
ゲートウェイ管理者として、モデルのルートを設定し、パイロットユーザーに利用を許可します。開発者に設定を配布する前に、サポートする各クライアントで接続をテストしてください。ゲートウェイ認証には、ネイティブのゲートウェイ OAuth、API key、または認証情報ヘルパーを使用します。ゲートウェイ認証と ChatGPT ワークスペースへのサインインを併用する場合は、 ゲートウェイ経由で ChatGPT にサインインするを参照してください。
前提条件
開発者に Codex を展開する前に、次のものが揃っていることを確認してください。
- 配布予定のベース URL と完全に一致する URL で HTTPS を提供するゲートウェイ。
- ゲートウェイ側で保持する上流プロバイダーの認証情報。
- 意図した上流モデルにマッピングされた、承認済みの Codex 向けモデルエイリアス。
- テスト済みの認証方法。ゲートウェイのネイティブ OAuth、スコープを限定したゲートウェイの API key、または認証情報ヘルパーを使用します。
- OAuth の場合、登録済みのパブリッククライアント、承認済みのテストユーザー、およびゲートウェイによる OAuth アクセストークンの検証サポート。
- API key またはヘルパーの場合、シークレットを配布する仕組み、またはテスト済みのヘルパー。
- 設定、必要なヘルパー、カタログファイルを配布する手段。
ゲートウェイの要件
Codex を接続する前に、ゲートウェイ製品が次の必須の動作を維持することを確認してください。
POST /v1/responsesで Codex の Responses API リクエストを受け付ける。- バッファリングせずに SSE イベントをストリーミングし、
response.completedで終了する。 - 再送された入力による後続ターンの継続を維持する。
- WebSocket または差分転送が有効な場合にのみ、
previous_response_idを維持する。 - 関数呼び出しと、それに対応する
function_call_output項目を維持する。 - 各 Codex 向けモデルエイリアスを、意図した上流モデルにルーティングする。
- ユーザーを個別に認証し、原因を隠さずに有用なエラーを返す。
ヘルスエンドポイント、/v1/models、Chat Completions のレスポンス、または 1 回のプレーンテキストの応答だけでは、ゲートウェイが要件を満たすとは判断できません。詳細な仕様については、ゲートウェイの互換性要件を参照してください。
ゲートウェイを展開する
デプロイ済みのゲートウェイで開発者が問題なく利用できることを確認するため、次の 5 つの確認項目を順番に完了してください。
モデル名とルーティングを選ぶ
Codex の model をゲートウェイのモデル名に設定します。その名前を承認済みの上流モデルにルーティングするよう、ゲートウェイを設定してください。
| ゲートウェイのモデル名 | Codex の構成 |
|---|---|
| 使用中の Codex バージョンに含まれる組み込みモデル名 | config.toml の model を、この正確な名前に設定します。 |
company-coding-model などのカスタムエイリアス |
エイリアスと対応するモデルのメタデータを含むリモートまたはローカルカタログを提供します。 |
カスタム名にはモデルカタログを使う
ローカルカタログには、models.json の例を出発点として使用してください。
ゲートウェイで Codex が認識しないモデル名を使用する場合は、モデルカタログを提供します。カタログには、その名前に対して Codex が使用する指示、推論オプション、コンテキスト上限、ツール機能が含まれます。一致するエントリがない場合、リクエストが意図したアップストリームモデルに到達しても、Codex は汎用設定を使用する可能性があります。
model_providers.<id>.model_catalog_url を使用してリモートカタログをホストし、モデルのメタデータを一元的に更新するか、model_catalog_json を使用してローカルファイルを配布します。ゲートウェイのネイティブ OAuth が唯一の認証手段の場合は、ローカルカタログを使用してください。OAuth だけではリモートカタログの検出は有効になりません。両方の設定については、設定リファレンスを参照してください。
使用している Codex のバージョンと互換性のあるカタログエンドポイントまたはファイルを、クラウドまたはゲートウェイのプロバイダーから入手してください。承認済みの各エイリアスと、そのモデルのメタデータが含まれていることを確認してください。カタログの実装については、 ゲートウェイとクラウド向けのモデルカタログの実装を参照してください。
リモートカタログを提供する
プロバイダーが提供する HTTPS カタログエンドポイントを使用してください。選択したプロバイダーの config.toml テーブルで、エンドポイントの完全な URL を配布してください。
model = "company-coding-model"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
model_catalog_url = "https://gateway.example.com/codex/models"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"CODEX_GATEWAY_API_KEY を Codex プロセスから利用できるようにします。推論をゲートウェイ経由でルーティングするには、base_url を別途設定します。省略すると、Codex は現在の認証モードに応じたデフォルトの OpenAI エンドポイントを使用します。
検出には、API key 認証、コマンドベースの認証、または Codex バックエンド認証が必要です。ゲートウェイのネイティブ OAuth またはカスタムヘッダーだけでは、検出は実行されません。
承認済みモデルが変わったら、プロバイダーと連携してカタログを更新してください。クライアントの設定を変更した後は、クライアントを再起動してください。
requirements.toml によって強制されているものも含め、有効な model_catalog_json 設定を削除します。この設定はリモート URL より優先され、取得を妨げます。
ローカルカタログを配布する
model_catalog_json を使用して、起動時にプロバイダー提供のファイルを読み込みます。ローカルのカスタムカタログは、同梱のカタログを置き換えます。
ゲートウェイのエイリアス、カタログの slug、Codex の model を company-coding-model に設定します。配布する Codex 設定の最初の TOML テーブルより前に、ファイルの実際の絶対パスを使って次の設定を追加してください。
model = "company-coding-model"
model_catalog_json = "/absolute/path/to/gateway-models.json"Codex は起動時にカタログを読み込むため、カタログを変更した後は CLI またはデスクトップアプリを再起動してください。
モデルのルーティングを検証する
各モデルについて、実際の Responses リクエストとゲートウェイの記録を使ってルーティングを検証します。/v1/models レスポンスは名前を調べる際には役立ちますが、モデルが必要なリクエストやツールの動作をサポートしている証拠にはなりません。
モデルのルーティングとツールの認可は、展開における別々の要素です。 MCP 接続、プラグインの配布、およびそれらのポリシーは個別に設定してください。
認証方法を選択する
ゲートウェイのネイティブ OAuth
- PKCE を使用した認可コードフローをサポートするパブリック OAuth クライアントを登録し、サインインできるユーザーまたはグループを承認します。
- 選択した Cookie またはカスタムヘッダー内の発行済みアクセストークンを検証するよう、ゲートウェイを設定します。承認済みのモデル、レート制限、予算を各ユーザーの ID に適用します。
- ゲートウェイのネイティブ OAuthに従って、認可 URL とトークン URL、パブリッククライアント ID、スコープ、任意のリソース、トークンの受け渡し設定、および固定リダイレクトポートがあればその値を収集します。対応するループバックリダイレクト URI を ID プロバイダーに登録します。
- 展開予定の CLI またはデスクトップアプリで、テストユーザーを使用してブラウザーでのサインイン、トークンの更新、アクセス権の取り消しをテストします。リモート CLI ユーザーの場合も含め、ブラウザーからコールバックに到達できることを確認してください。
ユーザーは個別にサインインします。配布するのは OAuth 設定であり、クライアントシークレット、ゲートウェイの API key、ヘルパー実行ファイルではありません。上流プロバイダーの認証情報はゲートウェイに保持してください。
API key または認証情報ヘルパー
- 使用状況を開発者ごとに把握し、アクセスを個別に取り消せるよう、開発者ごとにスコープを限定したゲートウェイ認証情報を 1 つ発行します。
- 各認証情報に対して、承認済みモデル、レート制限、予算、有効期限、更新期間を設定します。
- シークレットマネージャー、またはインストール済みの認証情報ヘルパーを通じて認証情報を配布します。上流プロバイダーとゲートウェイ管理者の認証情報を開発者のマシンに配置しないでください。
- ヘルパーを使用する場合は、コマンドによる認証の仕様に従い、配布前にトークンの取得と更新をテストします。
- 認証情報の更新方法と、サポートの問い合わせ先を開発者に伝えます。
ゲートウェイ経由で Codex をテストする
配布を始める前に、プロバイダーの設定に従い、配布予定のプロバイダーブロックと認証方法を使用して、他から分離したテストユーザーを 1 人設定します。
ゲートウェイがモデルカタログを提供する場合は、Codex と互換性のある models 配列を返すことを確認してください。ユーザーの認証情報を使用する OpenAI 推論では、必要な ChatGPT ヘッダーをゲートウェイが Codex バックエンドに転送することを確認してください。
パイロット運用で使用するクライアントのバージョン、オペレーティングシステム、プロバイダー ID、モデルエイリアス、認証方式を記録してください。サポートする予定の各 CLI またはデスクトップの利用環境で、以下の確認を行ってください。ゲートウェイのみの認証と、ChatGPT サインインを併用するゲートウェイ認証の両方を提供する場合は、それぞれの組み合わせを個別にテストしてください。
| 確認項目 | 操作 | 合格の判断基準 |
|---|---|---|
| 実効設定 | 設定レイヤーを調べ、意図したプロバイダー、モデル、要件が適用されていることを確認します。 | パイロットで配布した設定が使用されています。ユーザーやプロファイルのデフォルト設定によって別のルートが選択されていません。 |
| 接続 | 接続を確認するの手順に従います。 | 想定したプロバイダーとエイリアスが有効で、テストプロンプトが成功し、ゲートウェイのログでテストユーザーを特定できます。 |
| ストリーミング | 複数の段落からなる短い回答を求めます。 | テキストが逐次届き、使用中のトランスポートがresponse.completedを出力します。HTTP は個別にテストし、ゲートウェイが SSE イベントをバッファリングせずに転送することを確認します。 |
| ローカルツールの実行ループ | 読み取り専用権限を設定した使い捨てフォルダーで、最上位のファイルを一覧表示して要約するよう Codex に依頼します。 | Codex がローカルツールを呼び出し、結果を返し、編集せずに最終回答を生成します。 |
| フォローアップ | 同じスレッドで追加の質問をします。 | 回答で前のターンが参照され、ゲートウェイが再送された入力を受け入れます。WebSocket または増分トランスポートが有効な場合は、previous_response_idも保持されます。 |
| エラーとユーザーの紐付け | 意図的に無効にしたテスト用エイリアス、または期限切れのテスト用認証情報で繰り返します。 | クライアントがルーティングや認証に関する有用なエラーを受け取り、有効なリクエストは引き続きテストユーザーに紐付けられます。 |
自動承認が有効な場合は、使い捨てのテストフォルダーを使用して、適用予定のポリシーでレビューが必要となるツール操作を実行します。ゲートウェイがレビューリクエストを処理し、クライアントが承認判断を適用することを確認します。承認が不要な読み取り専用のツール呼び出しでは、この経路をテストできません。パイロットを拡大する前に、未対応のワークフローを記録してください。
今回の展開で既存ユーザーのプロバイダーが変わる場合は、サポートする各クライアントで、新しい会話と変更前に作成した会話をテストします。ユーザーが既存の会話を表示、継続、分岐できるかを記録し、実行できなくなるワークフローがあれば復旧手順を提供します。デフォルトのプロバイダーを変更すれば会話履歴も移行されるとは考えないでください。
これらの確認がすべて成功したら、開発者への引き継ぎを準備します。
設定を配布する
すべてのマシンで同じ接続経路を使用するために、ゲートウェイのベース URL、プロバイダー ID、承認済みのモデルエイリアス、認証設定を配布します。
配布するもの
ゲートウェイのネイティブ OAuth の場合は、プロバイダーテーブルと
[model_providers.<id>.gateway_oauth] テーブルを接続ガイドから取得し、上記で収集した登録値を設定して配布します。requires_openai_auth = false を維持し、
env_key、experimental_bearer_token、およびコマンドベースの auth テーブルは、
OAuth が唯一のゲートウェイ認証手段である場合に省略します。
認証情報ヘルパーの場合は、以下の config.toml ブロックを、選択した設定レイヤーを通じて配布します。使用している Codex バージョンが認識するモデルを使用するか、上記の対応するカタログを提供してください。トークンリゾルバーを、設定したコマンドパスにインストールします。
model = "gpt-6-sol"
model_provider = "enterprise-gateway"
web_search = "disabled"
[model_providers.enterprise-gateway]
name = "Organization Gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
[model_providers.enterprise-gateway.auth]
command = "/usr/local/bin/fetch-codex-gateway-token"
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000有効期間の短い静的なテストキーを使用する場合は、認証ブロックを削除し、env_key = "CODEX_GATEWAY_API_KEY" を [model_providers.enterprise-gateway] 内に配置して、その変数を TOML の外部で設定します。env_key とコマンドによる認証を併用しないでください。
デフォルトと必須設定を配布する
ユーザーが ChatGPT で Codex にサインインしない場合は、独自のサーバーからチーム設定を配布できます。Codex は、モデルリクエストのルーティング方法とは独立してこれらの設定を取得します。
設定の優先順位を参照して、デフォルトの配布先を選択します。強制適用する設定と macOS MDM のペイロードについては、管理対象の設定を参照してください。
macOS または Linux でホスト全体のデフォルトを設定するには、/etc/codex/config.toml を使用します。
Windows では、config.toml を %ProgramData%\OpenAI\Codex\ に配置します。ユーザーやプロファイルは、これらのデフォルトを上書きできます。リンク先のリファレンスには、サポートされる必須設定とファイルの配置場所が記載されています。
参照されるヘルパー実行ファイルとローカルカタログファイルは、個別に配布してください。
リモートカタログ URL を強制するには、完全なプロバイダー定義を
requirements.toml の [model_providers.<id>] 配下に配置します。強制されたプロバイダー定義は、通常の構成にある一致するプロバイダーテーブルを置き換えます。その base_url、認証設定、その他の必須フィールドを含めてください。プロバイダーの選択も強制する必要がある場合は、model_provider 要件を使用します。
model_catalog_json はローカルの JSON ファイルを指します。
requirements.toml を通じて強制適用すると、その必須設定によってパスは固定されますが、ファイルは配布されません。Codex の起動前に、その絶対パスにカタログを配置してください。
TOML には、解決済みの Windows の絶対パスを記述します。Codex は、
%ProgramData% を model_catalog_json やプロバイダー認証の command の値の中で展開しません。たとえば、次のパスは、展開時に実際にそこへファイルを配置した場合にのみ使用してください。
model_catalog_json = 'C:\ProgramData\OpenAI\Codex\models.json'
[model_providers.enterprise-gateway.auth]
command = 'C:\ProgramData\OpenAI\Codex\fetch-gateway-token.cmd'
args = ["print-token"]WSL 内の CLI は Linux のパスと Linux の CODEX_HOME を読み込みます。ネイティブの Windows 設定を自動的に継承することはありません。
ルーティングヘッダーを配布する
ゲートウェイが設定やツールに基づいてリクエストをルーティングする場合は、管理対象のrequirements.toml内のプロバイダーに、ゲートウェイが必要とするヘッダーを追加します。次の例では、ルーティング設定 ID を指定し、クライアントが Codex であることを示しています。
[model_providers.enterprise-gateway.http_headers]
x-portkey-config = "<gateway-routing-config-id>"
x-portkey-metadata = '{"tool_id":"codex"}'クライアント環境から取得するヘッダー値には、env_http_headersを使用します。テストリクエストを送信し、ゲートウェイのログで選択されたルートを確認します。ヘッダーのオプションについては、カスタムモデルプロバイダーを参照してください。
開発者に設定値を渡す
テスト済みのパイロットに対応するセットアップ手順を、開発者に一つ提供します。設定を一元的に配布する場合でも、次の情報を含めてください。
| 引き継ぎ項目 | 提供する情報 |
|---|---|
| 承認済みクライアント | パイロットで使用したクライアント、バージョン、オペレーティングシステム、およびインストールまたは更新の手順。 |
| 設定の配布 | 設定がすでに管理されているか、ローカルでのセットアップが必要か。別途インストールするヘルパーやカタログファイルがあれば明示します。 |
| 想定される接続 | プロバイダー ID、モデルエイリアス、および API パスを含むゲートウェイ URL。ユーザーが変更できる値を説明します。 |
| サインイン手順 | ChatGPT ワークスペースへのサインイン、ゲートウェイへの認証、またはその両方が必要か。必要なワークスペースとゲートウェイの認証方法を明示します。 |
| 認証情報とカタログ | OAuth 登録値、認証情報の環境変数、またはインストール済みヘルパーの設定に加え、カタログ URL や解決済みのローカルパス。シークレットは、承認済みのシークレット配布の仕組みを通じて提供します。 |
| 検証とサポート | 接続テスト、期待される結果、ゲートウェイの管理責任者、および障害報告時に含める情報。 |
管理対象のマシンを使用する開発者には、既存の設定を確認するを案内します。手動でセットアップする開発者には、プロバイダーを設定するを案内します。
今回の展開でプロバイダーが変わる場合は、既存の会話に関するテスト済みの手順を含めます。パイロットで問題が見つかった場合に備えて、展開責任者が以前の正常に動作していた設定を利用できるようにしておきます。
手動セットアップは、設定を強制適用する手段ではありません。プロジェクトローカルの .codex/config.toml では、機密性の高いプロバイダーや認証ルーティングのキーを上書きできません。
開発者のマシンから検証する
配布した設定が開発者のマシンに届いたことを確認するには、次の手順に従います。
- 承認済みクライアントと、必要なヘルパーやカタログファイルがインストールされていることを確認します。Codex を再起動し、引き継ぎ手順に記載されたサインインを完了します。
- 想定したプロバイダーとモデルを確認します。CLI では、
/statusを使用します。実効設定が引き継ぎ内容と異なる場合は、/debug-configで設定レイヤーを調べます。 - ゲートウェイに接続するに記載された簡単なテストを実行します。
- 追加の質問を一つして会話を継続できることを確認し、ゲートウェイのログでその開発者のリクエストを確認します。
サポートするクライアントと認証方法の組み合わせでパイロットが成功したら、アクセス対象を拡大します。クライアント、ゲートウェイ、ポリシーの更新後に再確認できるよう、テスト済みの設定と結果を展開手順とともに保管します。
展開時の問題を解決する
発生した問題を手がかりに、対処が必要な設定、認証情報、またはゲートウェイのレイヤーを特定します。
| 問題 | 対処方法 |
|---|---|
| 再起動後に期待するプロバイダーが表示されない。 | 優先して適用されている設定レイヤーを調べます。ユーザー設定やプロファイル設定がシステムのデフォルトを上書きしている可能性があります。 |
| すべてのユーザーで認証が失敗する。 | ゲートウェイ認証と上流プロバイダーの認証情報を確認し、どのサービスがリクエストを拒否したのかを特定します。 |
| 1 人のユーザーで認証が失敗します。 | そのユーザーの ID プロバイダーへのアクセス権、ゲートウェイ認証情報、またはトークンリゾルバーを確認します。 |
| ストリーミングが停止する。 | ゲートウェイのバッファリングと、終端の response.completed の転送を調べます。 |
| モデルが表示されない、または汎用の機能が使用される。 | カスタムエイリアスの場合は、ゲートウェイのエイリアス、Codex の model、カタログの slug が一致することを確認します。カタログのパスと、インストール済みの Codex バージョンとの互換性を確認してから、Codex を再起動します。 |
| Windows のパスが機能しない。 | 解決済みの絶対パスを使用します。TOML で単一のバックスラッシュを含む Windows パスを記述する場合は、単一引用符で囲んだ文字列を使用してください。 |
既存のゲートウェイ環境を再利用する
組織ですでにゲートウェイ経由で Claude Code を使用している場合は、ゲートウェイ製品、ネットワーク経路、ログ記録、Bedrock アクセスを再利用できる可能性があります。
Codex 向けの Responses ルート、認証情報、モデルエイリアス、config.toml を追加し、既存の動作している設定を維持します。Claude クライアントの設定と
/v1/messages の仕様では、Codex は設定されません。
| 既存の Claude 環境 | Codex への移行 |
|---|---|
| ゲートウェイ製品、DNS、TLS、プライベートネットワーク、ログ記録、秘匿化、監視 | これらのサービスを維持します。ゲートウェイの互換性要件を満たす Codex 向けルートを追加してください。 |
| Bedrock アカウント、プロバイダーの認証情報、IAM 境界、推論プロファイル、認証情報のローテーション | 新しい Codex エイリアスの背後にある上流モデルへのアクセスを許可する場合にのみ維持します。プロバイダーの認証情報はゲートウェイ側に保持します。 |
Claude の /v1/messages ルート、Bedrock InvokeModel の形式、Anthropic ヘッダー、Claude 固有の再試行やエラー |
これらを互換性の証拠として再利用しないでください。Codex には、POST /v1/responses、Responses のストリーミング、会話の継続、ツール呼び出し、有用なエラーが必要です。 |
ANTHROPIC_AUTH_TOKEN、ANTHROPIC_API_KEY、または apiKeyHelper |
Codex は apiKeyHelper をサポートしていません。ゲートウェイのネイティブ OAuth、env_key を使用したスコープ限定のキー、または Codex のコマンドベースのトークンリゾルバーを設定します。 |
Claude のモデル名、ANTHROPIC_MODEL、ANTHROPIC_DEFAULT_*_MODEL、modelOverrides、Bedrock プロファイルのマッピング |
ゲートウェイチームにモデル名の選定と必要なカスタムエイリアスの設定を依頼します。提供されたモデル名と、必要なモデルカタログ JSON を使用してください。 |
Claude の settings.json、managed-settings.json、JSON の env ブロック、plist、またはレジストリのペイロード |
同じ MDM または構成管理の配布経路を維持し、代わりに Codex の config.toml と、サポートされる requirements.toml の値を配布します。 |
安全に移行するには、次の手順を順番に完了してください。
- 現在の Claude の接続経路を把握します。ゲートウェイ URL、認証情報の取得元、必須ヘッダー、モデルエイリアス、Bedrock プロファイルのマッピング、管理対象の配布経路を確認してください。
- Codex 向けの Responses ルートと Codex のモデルエイリアスを並行して追加します。
- ゲートウェイのネイティブ OAuth、API key、認証情報ヘルパーのいずれかを選び、テストユーザーを一人認可します。静的な認証情報は
env_keyを通じて利用できるようにします。ヘルパーを使用する場合は、Codex のコマンドベースのリゾルバー仕様を実装してテストします。 - 手順 3 で選択した認証方法を使用し、その開発者向けにプロバイダーを設定します。管理された展開では、ゲートウェイを展開するに記載された Codex のパスと優先順位に合わせてペイロードを変換します。
- 開発者が実際に使用する CLI またはデスクトップ環境で簡単な接続確認を実行し、続いてゲートウェイ経由で Codex をテストするに記載されたストリーミング、会話の継続、ツール呼び出し、エラー、ログ記録、エイリアスによるルーティングの確認をすべて実行します。
- パイロットが成功したら、残りの開発者に設定を配布します。
モデルカタログのリファレンス
ローカルの models.json ファイルから始める
まず、Codex を実行するマシンでゲートウェイプロバイダーを設定して選択します。
Codex を実行するマシンに、このカタログをmodels.jsonとして保存します。
gateway-modelを、ゲートウェイが受け付ける正確なモデル ID に置き換えます。表示名は、モデルピッカーでユーザーに表示されるラベルです。
{
"models": [
{
"slug": "gateway-model",
"display_name": "Gateway model",
"base_instructions": "Help the user with their coding tasks.",
"supported_reasoning_levels": [],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"priority": 0,
"support_verbosity": false,
"truncation_policy": { "mode": "tokens", "limit": 10000 },
"experimental_supported_tools": []
}
]
}より大規模な例については、Codex のモデルカタログを参照してください。
model_catalog_jsonをconfig.toml内でファイルの絶対パスに設定します。
Codex を再起動し、Gateway model を選択してリクエストを送信します。ゲートウェイがslugに設定したモデル ID を受信したことを確認します。
同梱モデルのエイリアスを作成する場合は、使用中の Codex バージョンに対応するカタログエントリ全体をコピーし、slugとdisplay_nameを変更します。エイリアスに移行先がない場合は、upgradeをnullに設定します。これにより、モデルのコンテキストウィンドウ、推論オプション、ツール設定が保持されます。
クライアントにカタログを提供する
このページは、モデルカタログを定義し、モデルピッカーの基盤となる Codex Models 形式を実装する開発者向けです。ゲートウェイやクラウドサービスなどの推論プロバイダーを構築する場合は、この仕様を使用することで、 Codex デスクトップアプリと CLI がモデルを検出し、その指示と機能設定を使用できるようになります。
企業の管理者としてモデルカタログを制御する場合は、
model_catalog_urlの設定ガイドを参照してください。
この形式に対応するには、認証付きのカタログエンドポイントを実装します。リクエスト元の Codex バージョンに対応する上流プロバイダーの最新のデフォルト設定を取得し、オーバーライドを適用して、結果のカタログを返します。
client_version カタログエンドポイントを実装する
デフォルトのカタログエンドポイントは、プロバイダーの base_url 配下の /models です。たとえば、base_url = "https://gateway.example.com/v1" の場合、Codex は次のリクエストを送信します。
GET /v1/models?client_version=0.162.1
Authorization: Bearer <PROVIDER_ACCESS_TOKEN>デフォルトの検出は、コマンドによる認証と、ChatGPT などの Codex バックエンドによる認証に対応しています。コマンドによる認証を使わずに API key 認証を使用するカスタムプロバイダーでは、
model_providers.<id>.model_catalog_url を明示的に設定してリモート検出を有効にします。API key だけでは、デフォルトのパスでの検出は開始されません。
model_catalog_url を使用して、次のような完全なカタログ URL を指定します。
https://gateway.example.com/codex/models。デフォルトの
/v1/models エンドポイントを指定することもできます。Codex は /models を追加せず、この URL を直接使用します。
API key による検出では、features.api_key_model_discovery を有効にしておいてください。これはデフォルトで有効です。カスタムヘッダーだけでは検出は有効になりません。
Codex は、選択したプロバイダーの認証情報と設定済みヘッダーを送信し、
client_version とプロバイダーの query_params を追加します。カタログは、これらの認証情報の受信を許可されたサービスでホストしてください。
呼び出し元を認証し、対応する上流のデフォルト設定を取得して、オーバーライドを適用し、完全な ModelsResponse JSON を直接返します。すべてのエントリに、一意で空ではない slug を指定します。model_catalog_url が明示的に指定されている場合、Codex はリダイレクトと 1 MiB を超えるレスポンスを拒否します。推論リクエストでも引き続き、モデルへのアクセス制御を適用してください。
このエンドポイントを使用するクライアントから、有効になっている model_catalog_json 設定を削除してください。ローカルファイルが優先されるため、リモートから取得されなくなります。
クライアントのスキーマに合わせる
カタログリクエストの client_version クエリパラメーターを読み取ります。Codex は自身の
CLI バージョンを、プレリリースのサフィックスを除いた major.minor.patch 形式で送信します。デスクトップクライアントの場合、これは同梱の CLI のバージョンです。
公開 Codex リポジトリの対応する rust-v<version> タグを使用します。カスタムビルドの場合は、そのビルドのソースコミットを使用します。以下のリンクは rust-v0.162.1 を使用しています。クライアントに対応するリビジョンを選択してください。
- スキーマについては、
ModelsResponseとModelInfoのレスポンス型を参照してください。 - 完全な例については、同梱の
models.jsonを確認してください。これはカタログデータであり、JSON Schema ドキュメントではありません。
同梱ファイルはリリース時点のスナップショットです。カタログを生成する前に、最新のデフォルト設定を取得してください。
上流の最新のデフォルト設定を取得する
OpenAI モデルを提供するクラウドプロバイダーは、OpenAI からデフォルト設定を取得します。ゲートウェイは、クラウドまたは上流プロバイダーのカタログを読み取ることで、デプロイ済みモデルの設定と、アカウントおよびリージョンごとの利用可否を維持します。各段階でリクエスト元の Codex バージョンを渡し、各エンドポイントで個別に認証してください。
OpenAI からデフォルト設定を直接取得するには、同じ
client_version を指定して Codex のモデルエンドポイントを呼び出します。たとえば、OpenAI API key を使用する場合は次のとおりです。
curl --fail --silent --show-error \
'https://chatgpt.com/backend-api/codex/models?client_version=0.162.1' \
-H "Authorization: Bearer $OPENAI_API_KEY"ChatGPT との連携では、呼び出し元の ChatGPT アクセストークンと、必要に応じて ChatGPT-Account-ID ヘッダーを使用します。上流エンドポイントでの使用が許可された認証情報を使用してください。ゲートウェイ独自の API key では OpenAI に対する認証はできません。
最上位の models 配列を含むレスポンス全体を解析します。このエンドポイントは、指示、推論のデフォルト設定、ツール設定、コンテキストの上限、サービスティアなどの Codex メタデータを返します。公開の /v1/models エンドポイントでは、このカタログは提供されません。
Codex のバージョンが変わっていなくても、これらのデフォルト設定を更新してください。リクエストは意図した上流の ID の範囲に限定し、レスポンスのキャッシュ制御に従ってください。カタログは呼び出し元のアクセス権によって異なる場合があります。オーバーライドは個別に管理し、新しいデフォルト設定に再適用できるようにしてください。
プロバイダーのオーバーライドを適用する
そのバージョンのレスポンス構造を維持しながら、フィールドの値を変更します。
- モデルをフィルタリングして、呼び出し元が使用できるモデルだけを残します。各
slugをサポートされている推論ルートに対応付け、display_name、description、またはpriorityを調整します。モデル移行を伴わないエイリアスでは、upgradeをnullに設定します。 - 推論オプション、コンテキストの上限、入力モダリティ、サービスティアを、モデルとルートがサポートする値に設定します。デフォルト値は、サポートされている選択肢の範囲内にしてください。サービスティアがないルートでは、
service_tiersとadditional_speed_tiersを空にし、default_service_tierをnullに設定します。 - 代替設定をテスト済みでない限り、上流の指示とツール設定を維持してください。メタデータによってモデルの機能が追加されたり、推論へのアクセス権が付与されたりすることはありません。
ゲートウェイのモデルエイリアスについては、 モデルメタデータを提供する方法を参照してください。生成したカタログは、サポートする各 Codex バージョンでテストしてください。
公開の Rust 型を使用する
クライアントのスキーマと同じ公開 Git タグまたはコミットのクレートを使用します。
codex_protocol::openai_models::{ModelsResponse, ModelInfo}にはcodex-protocolを使用します。serde_json::from_slice::<ModelsResponse>()で解析し、catalog.modelsを編集して、serde_json::to_vec()でラッパー全体をシリアライズします。ラッパーは、モデルの指示に関する互換性フィールドを処理します。codex-models-manager::bundled_models_response()を使用すると、そのリビジョンに同梱されている静的カタログをModelsResponseとして読み込めます。上流の最新のデフォルト設定は取得しません。