ゲートウェイ経由で Codex を展開する

組織の LLM ゲートウェイ経由で Codex を展開します。モデルのルーティングを設定し、開発者の認証情報を発行して、検証済みの Codex 設定を配布します。

前提条件

開発者に Codex を展開する前に、次のものが揃っていることを確認してください。

• 配布予定のベース URL と完全に一致する URL で HTTPS を提供するゲートウェイ。
• ゲートウェイ側で保持する上流プロバイダーの認証情報。
• 意図した上流モデルにマッピングされた、承認済みの Codex 向けモデルエイリアス。
• スコープを限定したテスト用ゲートウェイ認証情報。
• シークレットの配布手段、またはテスト済みの認証情報ヘルパー。
• 設定、ヘルパー実行ファイル、必要なカタログファイルを配布する手段。

ゲートウェイの要件

Codex を接続する前に、ゲートウェイ製品が次の必須の動作を維持することを確認してください。

• POST /v1/responses で Codex の Responses API リクエストを受け付ける。
• バッファリングせずに SSE イベントをストリーミングし、response.completed で終了する。
• 再送された入力による後続ターンの継続を維持する。
• WebSocket または差分転送が有効な場合にのみ、previous_response_id を維持する。
• 関数呼び出しと、それに対応する function_call_output 項目を維持する。
• 各 Codex 向けモデルエイリアスを、意図した上流モデルにルーティングする。
• ユーザーを個別に認証し、原因を隠さずに有用なエラーを返す。

ヘルスエンドポイント、/v1/models、Chat Completions のレスポンス、または 1 回のプレーンテキストの応答だけでは、ゲートウェイが要件を満たすとは判断できません。詳細な仕様については、ゲートウェイの互換性要件を参照してください。

ゲートウェイを展開する

デプロイ済みのゲートウェイで開発者が問題なく利用できることを確認するため、次の 5 つの確認項目を順番に完了してください。

1. モデル名を選び、ルーティングを検証する。
2. 開発者の認証情報を発行する。
3. ゲートウェイ経由で Codex をテストする。
4. 設定を配布する。
5. 開発者のマシンから検証する。

モデル名とルーティングを選ぶ

Codex の model をゲートウェイのモデル名に設定します。その名前を承認済みの上流モデルにルーティングするよう、ゲートウェイを設定してください。

カスタム名にはモデルカタログを使う

ゲートウェイで Codex が認識しないモデル名を使う場合は、model_catalog_json を使用してください。カタログは、その名前に対して Codex が使用する指示、推論オプション、コンテキストの上限、ツール機能を提供します。一致するエントリがない場合、リクエストが意図した上流モデルに届いても、Codex は汎用設定を使用することがあります。

たとえば、company-coding-model を gpt-6-luna のエイリアスとして使用するには、次の手順に従います。

1. ゲートウェイに company-coding-model エイリアスを作成し、承認済みの上流の gpt-6-luna モデルにルーティングします。
2. 使用する Codex バージョンの Codex モデルカタログをダウンロードし、コピーを gateway-models.json として保存します。このファイルを出発点として使用してください。
3. コピー内の gpt-6-luna エントリを編集します。slug を company-coding-model に設定し、残りのメタデータが上流モデルとゲートウェイの機能に一致していることを確認します。モデル移行を伴わないエイリアスでは、upgrade を null に設定します。
4. エントリをトップレベルの models 配列に保持し、各クライアントにファイルを配布します。カスタムカタログは同梱のカタログを置き換えるため、ユーザーが選択する必要のあるモデルをすべて含めてください。

LiteLLM 経由で Bedrock を使用する場合は、必要なカタログの編集を適用してください。

ゲートウェイのエイリアス、カタログの 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 接続、プラグインの配布、およびそれらのポリシーは個別に設定してください。

開発者の認証情報を発行する

1. 使用状況を開発者ごとに把握し、アクセスを個別に取り消せるよう、開発者ごとにスコープを限定したゲートウェイ認証情報を 1 つ発行します。
2. 各認証情報に対して、承認済みモデル、レート制限、予算、有効期限、更新期間を設定します。
3. シークレットマネージャー、またはインストール済みの認証情報ヘルパーを通じて認証情報を配布します。上流プロバイダーとゲートウェイ管理者の認証情報を開発者のマシンに配置しないでください。
4. ヘルパーを使用する場合は、 コマンドによる認証の仕様 に従い、配布前にトークンの取得と更新をテストします。
5. 認証情報の更新方法と、サポートの問い合わせ先を開発者に伝えます。

ゲートウェイ経由で Codex をテストする

配布を開始する前に、ゲートウェイに接続するに従い、配布予定のプロバイダーブロックと認証情報の仕組みを使って、独立したテストユーザーを 1 人設定します。

開発者が使用するものと同じ CLI またはデスクトップ環境で、次の確認を実行します。

これらの確認が成功したら、開発者にゲートウェイに接続するを案内し、自分のマシンで設定と検証を行ってもらいます。

設定を配布する

すべてのマシンで同じ接続経路を使用できるよう、ゲートウェイのベース URL、 プロバイダー ID、承認済みのモデルエイリアス、認証情報の仕組みを配布します。

配布するもの

プロバイダーのデフォルトを設定するには、選択した設定レイヤーを通じて、この 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 とコマンドによる認証を併用しないでください。

デフォルトと必須設定を配布する

設定の優先順位を参照して、 デフォルトの配布先を選択します。強制適用する設定と macOS MDM のペイロードについては、管理対象の設定を参照してください。

macOS または Linux でホスト全体のデフォルトを設定するには、/etc/codex/config.toml を使用します。 Windows では、config.toml を %ProgramData%\OpenAI\Codex\ に配置します。ユーザーやプロファイルは、これらのデフォルトを上書きできます。リンク先のリファレンスには、サポートされる必須設定とファイルの配置場所が記載されています。

参照されているヘルパー実行ファイルやカタログファイルは、個別に配布してください。

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 設定を自動的に継承することはありません。

開発者に設定値を渡す

管理された配布手段がない場合は、各開発者にゲートウェイ URL、プロバイダー ID、モデルエイリアス、認証情報の変数またはリゾルバー、必要なカタログのパスを渡します。ゲートウェイに接続するを案内して、自分のマシンで設定と検証を行ってもらってください。

手動セットアップは、設定を強制適用する手段ではありません。プロジェクトローカルの .codex/config.toml では、機密性の高いプロバイダーや認証ルーティングのキーを上書きできません。

開発者のマシンから検証する

配布した設定が開発者のマシンに届いたことを確認するには、次の手順に従います。

1. Codex を再起動し、期待するプロバイダーとモデルを確認します。
2. ゲートウェイに接続するの短いテストを実行します。
3. 追加の質問を 1 回行って会話が継続することを確認し、その後ゲートウェイのログで、その開発者のリクエストを確認します。

展開時の問題を解決する

発生した問題を手がかりに、対処が必要な設定、認証情報、またはゲートウェイのレイヤーを特定します。

既存のゲートウェイ環境を再利用する

組織ですでにゲートウェイ経由で Claude Code を使用している場合は、 ゲートウェイ製品、ネットワーク経路、ログ記録、Bedrock アクセスを再利用できる可能性があります。 Codex 向けの Responses ルート、認証情報、モデルエイリアス、config.toml を追加し、 既存の動作している設定を維持します。Claude クライアントの設定と /v1/messages の仕様では、Codex は設定されません。

安全に移行するには、次の手順を順番に完了してください。

1. 現在の Claude の接続経路を棚卸しします。ゲートウェイ URL、認証情報の取得元、必要なヘッダー、モデルエイリアス、Bedrock プロファイルのマッピング、管理された配布経路を確認してください。
2. Codex 向けの Responses ルートと Codex のモデルエイリアスを並行して追加します。
3. スコープを限定した Codex の認証情報を 1 つ発行します。Codex で静的な認証情報を使用する場合は、その新しい認証情報を env_key を通じて利用できるようにします。Claude で認証情報ヘルパーを使用している場合は、Codex のコマンドによるリゾルバーの仕様を実装してテストします。
4. プロバイダーブロックを使って、その開発者の設定を行います。管理された展開では、ゲートウェイ経由で Codex を展開するに記載された Codex のパスと優先順位に合わせてペイロードを変換します。
5. 開発者が実際に使用する CLI またはデスクトップ環境で短い接続確認を実行し、その後、ゲートウェイ経由で Codex をテストするにあるストリーミング、会話の継続、ツール呼び出し、エラー、ログ記録、エイリアスのルーティングの確認をすべて実行します。
6. 試験導入が成功したら、残りの開発者に設定を配布します。

関連ドキュメント

• ゲートウェイに接続する
• MCP
• プラグイン
• 管理対象の設定