ゲートウェイに接続する

モデルゲートウェイを設定し、ネイティブのゲートウェイ OAuth、API key、または認証情報ヘルパーで認証します。

ゲートウェイ担当チームが提供するプロバイダー設定と認証方法を使用して、Codex を組織のモデルゲートウェイに接続します。ゲートウェイは、モデルへのリクエストを Amazon Bedrock などのバックエンドにルーティングします。

既存の構成を確認する

管理者がテストした Codex クライアントとバージョンをインストールします。組織が設定を管理している場合は、そのクライアントを開き、引き継ぎ資料に記載されたサインイン手順を完了してください。以下のプロバイダー設定例はスキップできます。

  • CLI では、選択されているプロファイルを確認し、codex doctor を実行します。起動後に、 /status を使って有効なモデルとプロバイダーを確認します。
  • macOS アプリでは、~/.codex/config.toml または組織から配布された管理対象の構成を確認します。
  • Windows アプリでは、%USERPROFILE%\.codex\config.toml または組織から配布されたシステム構成を確認します。

想定するゲートウェイプロバイダーとモデルがすでに有効になっている場合は、管理者から提供されたサインイン手順を完了してから、接続を確認するに進んでください。管理対象のマシンに2つ目のプロバイダー設定を追加しないでください。設定が管理者の引き継ぎ資料と異なる場合は、ローカルファイルを編集する前に、どの設定レイヤーから設定を適用するべきかを確認してください。

ゲートウェイの接続情報を入手する

手動で設定する場合は、ChatGPT ワークスペースへのサインイン、ゲートウェイ認証、またはその両方が必要かどうかを確認してください。

Codex を自分で設定するには、ゲートウェイ担当チームから以下の値を入手してください。

  • API パスを含む HTTPS ゲートウェイのベース URL(例:https://gateway.example.com/v1)。
  • 使用するモデル名とプロバイダー ID。
  • 認証方法:ネイティブのゲートウェイ OAuth、スコープを限定した API key とその環境変数、またはインストール済みの認証情報ヘルパー。
  • OAuth の場合は、認可 URL、トークン URL、パブリッククライアント ID、必要なスコープ。Cookie またはカスタムヘッダーを使用するゲートウェイの場合は、その名前。
  • 必要なモデルカタログの URL、またはカタログファイルとそのローカルの絶対パス。

プロバイダーを構成する

macOS または Linux では config.toml を ~/.codex/config.toml で開き、 Windows では %USERPROFILE%\.codex\config.toml で開きます。

この例を既存の構成に統合し、URL とモデルを管理者から提供された値に置き換えます。既存のキーやテーブルを重複して定義しないでください。この例では gpt-6-sol を使用しています。カスタムカタログなしで使用するのは、使用中の 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"
requires_openai_auth = false

次に、ゲートウェイ担当チームが提供する認証設定を追加します。

enterprise-gateway はプロバイダー ID の例です。同じ ID を model_provider と、それに対応するプロバイダーおよび認証のテーブルで使用してください。この例では、最初の接続テストのためにウェブ検索を無効にしています。有効にする前に、管理者が機能のサポート状況を確認する必要があります。

モデルカタログを設定する

選択したモデルの機能情報と指示を Codex がどのように取得するか、ゲートウェイ担当チームに確認してください。

  • 組み込みの名前: ゲートウェイが使用中の Codex バージョンに同梱された正確なモデル名を受け付け、対応するモデルにルーティングする場合は、model をその名前に設定します。Codex はすでにそのメタデータを持っています。
  • カタログエンドポイント: ゲートウェイが Codex 互換のメタデータを提供する場合は、カタログの完全な URL を使用します。Codex カタログレスポンスを実装する /v1/models エンドポイントも使用できます。モデル ID を列挙するだけのレスポンスでは、カスタムエイリアスに必要な情報が不足します。
  • カタログファイル: ゲートウェイがカスタムエイリアスを使用し、管理者がファイルを配布する場合は、ローカルの models.json の例を使用します。認証手段がネイティブのゲートウェイ OAuth のみで、カスタムメタデータが必要な場合は、ローカルファイルを使用してください。

API key またはヘルパーによる認証で、管理者からカタログ URL が提供されている場合は、既存の [model_providers.enterprise-gateway] テーブルに追加します。

model_catalog_url = "https://gateway.example.com/codex/models.json"

有効な model_catalog_json 設定がある場合は削除してください。この設定は URL より優先されます。管理者は、リモートカタログのセットアップでエンドポイントの要件を確認できます。

管理者からローカルモデルカタログファイルが提供された場合は、そのファイルを保存し、ファイルの絶対パスを使用して、最初の TOML テーブルの前に model_catalog_json を追加します。カスタムエイリアスには、一致するカタログメタデータが必要です。例:

model_catalog_json = "/etc/codex/gateway-models.json"

管理者からセットで提供されたモデル名とカタログを使用してください。指定した場所にファイルが存在しない場合は、カタログパスを追加しないでください。

認証方法を選択する

ブラウザーでサインインする場合はネイティブのゲートウェイ OAuth、スコープを限定した認証情報を使用する場合は API key、組織からコマンドが提供されている場合は認証情報ヘルパーを使用します。

{/* prettier-ignore */}

ネイティブのゲートウェイ OAuth を使用する

ゲートウェイ OAuth は、ChatGPT へのサインインとは独立して機能します。Microsoft Entra ID など、組織の ID プロバイダーが発行するアクセストークンをゲートウェイが受け付ける場合に使用します。Codex は、ブラウザーでのサインインと認証情報の暗号化保存を処理し、認可サーバーがリフレッシュトークンを発行する場合はトークンの更新も処理します。

ゲートウェイのみで認証する場合、Codex CLI 0.166.0 以降はデフォルトで Authorization: Bearer <gateway access token> にアクセストークンを含めて送信します。このプロバイダーの http_headers または env_http_headers から Authorization エントリを削除してください。

ゲートウェイチームは、PKCE を使用する認可コードフローに対応したパブリック OAuth クライアントを登録する必要があります。次のテーブルをプロバイダー設定に追加し、 config.toml 内の URL とクライアント ID を実際の値に置き換えてください。

[model_providers.enterprise-gateway.gateway_oauth]
authorization_url = "https://login.example.com/oauth/authorize"
token_url = "https://login.example.com/oauth/token"
client_id = "YOUR_PUBLIC_CLIENT_ID"
# redirect_port = 43127

ID プロバイダーとゲートウェイが要求する値を使用して、このテーブルに scopes と、必要に応じて resource を追加します。プロバイダーが要求する場合は、リフレッシュトークンに必要なスコープをリクエストしてください。Codex は、デフォルトで使用可能なループバックポートを使用します。 ID プロバイダーが固定のリダイレクト URI を要求する場合は、redirect_port を設定し、この例では http://127.0.0.1:43127/callback を登録します。

ゲートウェイが Cookie またはカスタムヘッダーを必要とする場合は、OAuth テーブルにオプションの delivery フィールドを設定します。ゲートウェイが検証する方式を選択してください。

delivery = { kind = "cookie", name = "auth-openid" }
delivery = { kind = "header", name = "X-Gateway-Token", scheme = "Bearer" }

デプロイ環境で ChatGPT へのサインインも必要な場合は、上記の Cookie または個別のゲートウェイヘッダーを使用してください。ChatGPT サインインを有効にするを参照してください。

静的な API key のみを受け付けるゲートウェイでは、このフローを使用する前に OAuth トークンとその送信方式への対応を追加する必要があります。ゲートウェイは引き続き、 Bedrock 用の AWS 認証情報など、独自の上流サービスの認証情報を管理します。

OAuth のみを認証情報として使用する場合は、requires_openai_auth = false を維持し、ゲートウェイの認証情報に使用していた env_key、experimental_bearer_token、または auth の設定を削除してください。カスタムモデルのメタデータが必要な場合は、ローカルモデルカタログを使用してください。OAuth だけではリモートカタログの検出は有効になりません。

デスクトップアプリを再起動し、ゲートウェイへのサインイン案内に従ってブラウザーを開きます。 CLI では、codex を起動し、Codex が初めてゲートウェイにアクセスしたときに、ブラウザーでのサインイン手順に従います。組織のサインインと MFA を完了してから、クライアントに戻ります。認可が期限切れになった場合や Codex が更新できない場合は、案内に従って再度サインインしてください。

ネイティブのゲートウェイ OAuth には、ブラウザーと、到達可能なループバックコールバックが必要です。デバイスコードへのフォールバックはありません。SSH 経由で CLI を実行する場合は、OAuth テーブルに redirect_port = 43127 を設定し、前述の対応するリダイレクト URI を登録します。Codex を起動する前に、ブラウザーを使用するマシンからそのポートを転送してください。

ssh -L 43127:127.0.0.1:43127 user@remote

その SSH セッションで codex を起動し、ゲートウェイのサインイン URL をローカルのブラウザーで開きます。コンテナー内の CLI にも、ブラウザーから到達可能なコールバックが必要です。コールバックに到達できるように設定できない場合は、代わりに API key または認証情報ヘルパーを使用してください。

ChatGPT サインインを有効にする(推奨)

組織で ChatGPT ワークスペースを使用している場合、ユーザーはサインインすることで、ファーストパーティ製プラグインなどの利用対象の機能にアクセスできます。ワークスペースの管理設定が適用され、モデルへのリクエストは引き続きゲートウェイが処理します。利用可能な機能を比較する。

手動で設定する場合は、サインインする前に既存の [model_providers.enterprise-gateway] テーブルを更新してください。

  1. requires_openai_auth = true を設定し、base_url はゲートウェイを指す状態にします。Codex が OpenAI の認証情報を主認証に使用するように、env_key、experimental_bearer_token、およびプロバイダーの auth の設定を削除してください。
  2. ゲートウェイの認証情報は別途送信します。ネイティブのゲートウェイ OAuth の場合は、ゲートウェイが受け付ける Cookie またはカスタムヘッダーを使用するように gateway_oauth.delivery を設定します。API key または認証情報ヘルパーの場合は、カスタム認証ヘッダーを使用してください。Authorization は OpenAI の認証情報専用にしてください。

管理者が指定した ChatGPT ワークスペースにサインインしてください。求められた場合はゲートウェイへのサインインを完了し、接続を確認してください。

管理者は、管理対象のプロバイダー設定を配布し、認証情報の転送を確認できます。

ゲートウェイで認証情報を処理する

ゲートウェイは、モデルへのリクエストごとに 2 つの認証情報を受け取ります。たとえば、Codex がゲートウェイの OAuth トークンを Cookie で送信する場合は、次のようになります。

POST /backend-api/codex/responses
Authorization: Bearer <ChatGPT token>
ChatGPT-Account-ID: <workspace ID, when available>
Cookie: auth-openid=<gateway token>

ゲートウェイの認証情報を検証し、その Cookie またはカスタムヘッダーを削除します。ログから認証情報と機密性の高いリクエストデータを除去します。上流へのリクエストに使用する認証情報を選択してください。

  • OpenAI で直接推論を行うためにユーザーの認証情報を転送する(推奨)。 これにより、OpenAI は使用量をそのユーザーに紐付け、ユーザーの推論設定を適用できます。このルートでは、ゲートウェイは /models と /responses を https://chatgpt.com/backend-api/codex にプロキシし、Authorization と、存在するすべての ChatGPT-Account-ID ヘッダーを変更せずに転送する必要があります。
  • ゲートウェイで推論プロバイダーへの認証を行う。 そのプロバイダー用にゲートウェイで設定された認証情報を使用します。上流へのリクエストには、ユーザーの OpenAI トークンと ChatGPT-Account-ID ヘッダーを含めないでください。

次の図は、OpenAI での推論に推奨されるルートを示しています。

ChatGPT サインインとゲートウェイキーを併用する仕組み
起動ヘルパーを通じて認証情報取得コマンドを再利用します。同じゲートウェイキーの送信先が Authorization から X-Gateway-Key に変わり、ChatGPT サインインによって Authorization が提供されます。
ゲートウェイは X-Gateway-Key を検証して削除し、ChatGPT の Authorization と、アカウント ID があればそれも変更せずに Codex バックエンドへ転送します。
ChatGPT サインインとゲートウェイ OAuth を併用する仕組み
API key によるゲートウェイ認証をネイティブのゲートウェイ OAuth に置き換え、ChatGPT サインインと併用します。
ゲートウェイは自身の OAuth Cookie を処理し、ChatGPT の認証情報を Codex バックエンドへ転送します。

ルーティングヘッダーを追加する(任意)

管理者から提供されたルーティング設定を使用してください。ゲートウェイの運用担当者は、これらの設定を配布し、ゲートウェイのログで選択されたルートを確認できます。

このゲートウェイルートを使用するのは、モデルプロバイダーへのリクエストのみです。音声セッションは別のルートを使用します。ワークスペースへのサインイン、MCP server、プラグインも、別のネットワーク経路を使用する場合があります。

クライアントを起動する

ChatGPT サインインを使用する場合は、クライアントを起動し、管理対象の設定を提供するワークスペースにサインインします。ネイティブのゲートウェイ OAuth を使用する場合は、案内が表示されたら組織のゲートウェイへのサインインも完了してください。その後、接続を確認します。

ローカルで設定したプロバイダーの場合は、使用するクライアントの手順に従ってください。

CLI を構成する

CLI は、macOS または Linux ではデフォルトで ~/.codex/config.toml を読み取ります。プロバイダーの設定を保存したら、codex を実行します。WSL 内では、CODEX_HOME が別の場所を指していない限り、Linux の構成とパスを使用してください。

macOS アプリを構成する

macOS アプリは同じ ~/.codex/config.toml を読み取ります。プロバイダーの設定を保存したら、アプリを再起動します。認証情報に環境変数を使用する場合は、アプリのプロセスから利用できることを確認してください。

Windows アプリを構成する

プロバイダーの設定を %USERPROFILE%\.codex\config.toml に配置し、アプリを再起動します。コマンドベースの認証では、管理者がインストールしたリゾルバーを使用してください。たとえば、Unix の認証テーブルを次の内容に置き換えます。

[model_providers.enterprise-gateway.auth]
command = 'C:\Program Files\OpenAI\Codex\fetch-codex-gateway-token.exe'
args = ["print-token"]
timeout_ms = 30000
refresh_interval_ms = 300000

Windows の TOML では、単一引用符で囲まれたリテラル文字列はバックスラッシュを保持します。 Unix のカタログパスも置き換えてください。たとえば、 'C:\ProgramData\OpenAI\Codex\models.json' のように、管理者から提供された実際のパスを使用します。

MCP serverとプラグインは別途構成してください。モデルゲートウェイの認証情報では、ツールや接続先システムへのアクセスは認可されません。

接続を確認する

管理者から引き継いだプロバイダー ID とモデルエイリアスを使用してください。プロバイダーは設定済みの接続を識別し、モデルエイリアスはその接続を経由するモデルを識別します。ChatGPT サインインとゲートウェイ認証はアクセスを制御し、両方が必要な場合もあります。

構成を変更したら、クライアントを再起動します。CLI では codex を起動し、 /status を使って有効なモデルとプロバイダーを確認します。デスクトップアプリでは、選択されているモデルと構成を確認します。

新しいタスクで次のプロンプトを送信します。

Reply with exactly: gateway-ok

想定される応答は gateway-ok です。応答だけでは、どの経路で処理されたかは証明できません。ゲートウェイにユーザー、モデルエイリアス、意図した上流への経路が記録されたことを管理者に確認してもらってください。モデルに名前を尋ねてモデルを特定しないでください。

接続の問題を解決する

症状 確認する内容
想定しているプロバイダーが有効になっていない。 選択されているプロファイルと構成の優先順位を確認します。トップレベルのキーがプロバイダーテーブル内に入っていないことを確認してください。
OAuth サインインまたはトークンの受け渡しが失敗します。 パブリッククライアントの登録、リダイレクト URI、スコープ、設定した Cookie またはヘッダーを確認します。ゲートウェイが発行されたアクセストークンを受け入れることを確認してください。
API key またはヘルパーによる認証が失敗します。 認証情報の変数がクライアントプロセスに渡されているか、またはインストール済みのヘルパーが有効なトークンを取得できるかを確認します。ゲートウェイ認証と上流の認証を区別して調査するよう管理者に依頼してください。
モデルが見つからない。 提供されたモデル名を確認し、その経路を確認するよう管理者に依頼してください。
モデルが想定外の機能を使用する。 カタログのメタデータがエイリアスの参照先モデルと一致するかを確認するよう、管理者に依頼してください。
ストリーミングが止まる、または後続のやり取りに失敗する。 プロキシのバッファリング、終端の response.completed イベント、ゲートウェイの互換性を確認するよう、ゲートウェイのオーナーに依頼してください。
カタログまたはヘルパーのパスが機能しない。 Codex を実行している環境で、設定された絶対パスにファイルが存在することを確認してください。

サポートを依頼する際は、クライアントのバージョン、オペレーティングシステム、想定するプロバイダーとモデルエイリアス、認証方式、失敗した手順を含めてください。ゲートウェイの管理担当者がリクエストを特定できるように、エラーメッセージとリクエスト時刻も含めてください。トークン、Cookie、認証ヘッダー、機密性の高いプロンプトは削除してください。認証情報ファイルや、シークレットを含む設定ダンプは送信しないでください。

既存のゲートウェイデプロイを使用する

ゲートウェイチームに Codex のプロバイダー設定と承認済みのモデルエイリアスを確認してください。チームがまだ Codex のルートを有効にしていない場合は、管理者向け移行チェックリストを共有してください。

関連ドキュメント