# Codexを外部モデルAPIにつなぐ：MCPではなくproviderを設定する

> Responses API互換性を確認し、Codexのcustom model providerをユーザー設定に分離。APIキーを環境変数で渡し、認証・モデル・SSE・429を切り分けます。

- Source: https://www.aifreeapi.com/ja/posts/codex-third-party-api
- Language: ja
- Published: 2026-08-25
- Updated: 2026-08-25
- Publisher: AI Free API (https://www.aifreeapi.com)

Codexでいう「外部API連携」は、目的を先に分ける必要があります。GitHub、データベース、社内サービスなどを道具として追加するならMCPです。一方、Codexが推論に使うモデルそのものを外部サービスへ切り替えるなら、設定するのは **custom model provider** です。

このページが扱うのは後者です。必要なのはAPIキーだけではありません。外部サービスがResponses APIを実装していること、その経路に実在するモデルIDを使うこと、認証方式が合うこと、ストリームが最後までCodexの期待する形式で返ることが必要です。

「OpenAI互換」という表記だけでは判定できません。`/v1/chat/completions`だけを実装したサービスも同じ表現を使えますが、OpenAIの現行[Configuration Reference](https://learn.chatgpt.com/docs/config-file/config-reference#configtoml)では、Codexの`wire_api`に指定できるのは`responses`だけです。サービス側の一次資料にResponses endpointがなければ、URLに`/responses`を足して試すのではなく、提供元へ確認します。

![MCPとcustom model providerを目的で分け、安全な設定、経路証明、障害切り分けまで示す全体図](https://www.aifreeapi.com/posts/ja/codex-third-party-api/img/mcp-vs-provider-setup.webp)

## 既存環境を壊さずに試す

日常利用のOpenAIルートを残したい場合、主設定を直接置き換えるより、専用profileを作る方が戻しやすくなります。現在の[Advanced Configuration](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers)では、`~/.codex/名前.config.toml`を`--profile 名前`で重ねられます。

`~/.codex/third-party.config.toml`を作り、サービス固有の値だけを入れます。

```toml
model = "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から起動します。

```bash
export 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側の両方で行う

![MCPとproviderの目的分岐、Responses互換性の一次資料確認、両端の証拠をまとめた最短判断フロー](https://www.aifreeapi.com/posts/ja/codex-third-party-api/img/compatibility-decision-checklist.webp)

起動時に外部モデル名が表示されても、それはprofileを読めた証拠にすぎません。通信先の証拠にはなりません。最初は機密ファイルのない空directoryで起動し、ファイル操作やtoolを必要としない固定の短文だけを返させます。

次の3点が一致したときに、基本ルートが成立したと判断できます。

- Codexの現在sessionが意図したモデルIDを示す。
- 短い応答がstream errorや再接続なしで完了する。
- providerまたはgatewayのdashboardに、同時刻・同モデルのrequest、status、usageが現れる。

request IDがある場合は時刻と一緒に記録します。キーや不要なprompt本文は記録しません。providerがモデルaliasを書き換える場合もあるため、Codex側の表示とprovider側の実績を照合することに意味があります。

たとえばDeepSeekは、現在の[公式Codex接続文書](https://api-docs.deepseek.com/quick_start/agent_integrations/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の診断](/ja/posts/codex-rate-limits)、長く止まる場合は[Codexタイムアウトの切り分け](/ja/posts/codex-timeout)を使えます。設定が反映されない場合は[config.tomlの優先順位と境界](/ja/posts/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まで失われます。