Codexでいう「外部API連携」は、目的を先に分ける必要があります。GitHub、データベース、社内サービスなどを道具として追加するならMCPです。一方、Codexが推論に使うモデルそのものを外部サービスへ切り替えるなら、設定するのは custom model provider です。
このページが扱うのは後者です。必要なのはAPIキーだけではありません。外部サービスがResponses APIを実装していること、その経路に実在するモデルIDを使うこと、認証方式が合うこと、ストリームが最後までCodexの期待する形式で返ることが必要です。
「OpenAI互換」という表記だけでは判定できません。/v1/chat/completionsだけを実装したサービスも同じ表現を使えますが、OpenAIの現行Configuration Referenceでは、Codexのwire_apiに指定できるのはresponsesだけです。サービス側の一次資料にResponses endpointがなければ、URLに/responsesを足して試すのではなく、提供元へ確認します。
既存環境を壊さずに試す
日常利用のOpenAIルートを残したい場合、主設定を直接置き換えるより、専用profileを作る方が戻しやすくなります。現在のAdvanced Configurationでは、~/.codex/名前.config.tomlを--profile 名前で重ねられます。
~/.codex/third-party.config.tomlを作り、サービス固有の値だけを入れます。
tomlmodel = "provider-model-id" model_provider = "acme" [model_providers.acme] name = "Acme Model API" base_url = "https://api.example.com/v1" env_key = "ACME_API_KEY" wire_api = "responses"
provider-model-idとURLは説明用です。利用するサービスのResponses文書にある値へ置き換えてください。acmeはローカルで決めるIDですが、上のmodel_providerとテーブル名を一致させます。openai、ollama、lmstudioは予約済みなので、custom provider名として上書きできません。
このブロックをrepository内の.codex/config.tomlへ置かない点も重要です。providerと認証はmachine-local設定であり、Codexはproject設定にあるmodel_providerとmodel_providersを無視します。チームへ共有すべきなのは「どのproviderを使うか」という秘密付き設定ではなく、必要なら公開可能なセットアップ説明と適用条件です。
APIキーは値ではなく参照先を書く
env_key = "ACME_API_KEY"は、Codexがその名前の環境変数からキーを読む指定です。TOMLへ本物のキーを書く行ではありません。
macOS、Linux、WSLでは同じshellから起動します。
bashexport ACME_API_KEY="実際のキー" codex --profile third-party
PowerShellの現在のセッションなら次の形です。
powershell$env:ACME_API_KEY = "実際のキー" codex --profile third-party
公式リファレンスにはexperimental_bearer_tokenもありますが、直接tokenを置く方法は非推奨で、env_keyが案内されています。キーをdotfiles repository、サンプル.env、画面共有、エラーログへ残さないでください。
CLIでは動くのにDesktopやIDE extensionではキーが見つからない場合、URLより先に起動環境を確認します。Dockやスタートメニューから起動したprocessは、別のterminalで一時的にexportした値を引き継がないことがあります。独自headerやquery parameterが必要なproviderでは、その一次資料に従ってenv_http_headers、http_headers、query_paramsを使い、他社の認証例を流用しません。
成功判定は画面とprovider側の両方で行う
起動時に外部モデル名が表示されても、それはprofileを読めた証拠にすぎません。通信先の証拠にはなりません。最初は機密ファイルのない空directoryで起動し、ファイル操作やtoolを必要としない固定の短文だけを返させます。
次の3点が一致したときに、基本ルートが成立したと判断できます。
- Codexの現在sessionが意図したモデルIDを示す。
- 短い応答がstream errorや再接続なしで完了する。
- providerまたはgatewayのdashboardに、同時刻・同モデルのrequest、status、usageが現れる。
request IDがある場合は時刻と一緒に記録します。キーや不要なprompt本文は記録しません。providerがモデルaliasを書き換える場合もあるため、Codex側の表示とprovider側の実績を照合することに意味があります。
たとえばDeepSeekは、現在の公式Codex接続文書でResponses形式のネイティブ対応と自社モデル設定を説明しています。これはDeepSeek経路の根拠です。別のgatewayが同じ「OpenAI互換」を掲げていても、同等の証明にはなりません。
エラーを変更箇所へ戻す
| 症状 | まず疑う境界 | 確認すること |
|---|---|---|
| 設定keyが不明、TOML parse error | Codex versionまたは構文 | codex --version、table名、引用符、現行reference |
| 環境変数がない | 起動process | 同じshellからの起動、Desktop/IDEの環境変数 |
| 401 / 403 | key、header、account/project権限 | provider consoleのkey状態とモデル権限 |
| 404 / model not found | base URLまたはモデル対応 | Responsesの正確なpathとprovider model ID |
| 接続後すぐparse error | response形式 | Chat Completions-only endpointを止める |
| 途中で停止、reconnectを繰り返す | SSE、proxy timeout、upstream | 切断時刻とrequest IDを両側logで照合 |
| 429 | provider、gateway、モデル上限 | statusを返した系統の残高・rate limit |
429が確定した場合はCodex 429の診断、長く止まる場合はCodexタイムアウトの切り分けを使えます。設定が反映されない場合はconfig.tomlの優先順位と境界を確認します。
短いtextが成功しても、機能が同等とは限りません。custom providerのstandalone web searchは既定でfalseで、flagだけではprovider endpoint、model、runtime、policyの不足を補えません。画像入力、tool call、reasoning summary、WebSocket、plugin、cloud機能も、実際に必要なものだけ個別に確認します。
第三者routeの請求、rate limit、保存方針、地域、supportはそのproviderが所有します。ChatGPTの契約残量は第三者の残量を示しません。元へ戻すときはcustom sessionを終了し、--profile third-partyを付けずに起動します。主設定へコピーした場合も、追加したmodel、model_provider、該当provider tableだけを削除します。~/.codex全体を消すと、無関係な認証、MCP、rules、historyまで失われます。
