# Codex カスタムプロバイダー設定：APIキーとBase URLの選び方

> キーの発行元とリクエストの送信先を先に決めると、APIキー認証、openai_base_url、別 provider のどれを使うべきかと、失敗時の担当が明確になります。

- URL: https://blog.laozhang.ai/ja/posts/codex-config-toml
- Published: 2026-08-04
- Updated: 2026-09-01
- Author: LaoZhang AI Team (https://blog.laozhang.ai/ja/about)
- Topic: 開発ツールとエージェント
- Tags: OpenAI Codex, Codex APIキー, Codex Base URL, カスタムプロバイダー, config.toml

---
Codex に外部 API をつなぐとき、APIキー、Base URL、model 名を一つのフォームのように扱うと、設定は読まれても route が成立しません。OpenAI のキーを別 provider の URL に送ったり、第三者 key を保存したまま OpenAI login を要求したりすると、`401` の owner さえ判断できなくなります。

最初に「誰が credential を発行し、誰が model request を受け取るか」を決めます。

- OpenAI Platform が key と API billing を持つなら、ローカル Codex の OpenAI API-key login。
- built-in `openai` provider のまま proxy、router、対象地域 endpoint を使うなら `openai_base_url`。
- 別サービスが key、model namespace、残高、support を持つなら `[model_providers.<id>]`。
- 管理下の local endpoint が本当に認証不要なら、auth field のない custom provider。

本ページは 2026 年 9 月 1 日の OpenAI [Advanced Configuration](https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers) と [Authentication](https://learn.chatgpt.com/docs/auth) を基準にしています。Codex の schema は更新されるため、古い設定例より現行の一次資料を優先してください。

## 先に route の5要素をそろえる

変更前に次の値をメモします。

| 要素 | placeholder | 確定すること |
| --- | --- | --- |
| Credential issuer | OpenAI Platform / `company_gateway` | 認証、account、billing の owner |
| Provider ID | built-in `openai` / 独自 ID | Codex が選ぶ provider block |
| Base URL | `https://gateway.example.com/v1` | request の実際の宛先 |
| Model ID | `EXACT_PROVIDER_MODEL_ID` | 同じ provider 内の model namespace |
| 必要 capability | Responses、streaming、tools | 合格させるべき実際の機能 |

![Codex の APIキー認証、Base URL 変更、別 provider と user config の境界を整理したルート図](https://blog.laozhang.ai/posts/ja/codex-config-toml/img/route-and-auth.webp)

一つの行だけ別サービスを指しているなら、そのまま起動しません。「OpenAI-compatible」は入力形式の手掛かりであり、Codex が必要とする Responses、stream event、tool call、model access まで証明する表現ではありません。

## OpenAI APIキーで Codex にログインする場合

OpenAI は ChatGPT login と API-key login をローカル Codex の別 route として説明しています。CLI では key を引数にせず、stdin から渡せます。

```bash
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status
```

この route の usage は OpenAI Platform account と project に属し、API pricing で計上されます。ChatGPT plan の included usage ではありません。また Codex cloud は ChatGPT login が必要なので、API key だけで全 cloud feature が同じになるわけではありません。

credential cache は `~/.codex/auth.json` または OS credential store に置かれます。file storage の `auth.json` は password と同じです。Git に commit せず、issue、chat、support ticket に貼らず、認証方式は `codex login status` で確認します。

billing route の選択自体が未解決なら、先に [Codex APIキーとサブスクリプション](https://blog.laozhang.ai/ja/posts/codex-api-key-vs-subscription) を確認してください。

## built-in OpenAI の送信先だけ変える場合

OpenAI auth と built-in provider を保ち、適切な proxy や region endpoint を通す場合、専用の user setting があります。

```toml
# ~/.codex/config.toml
openai_base_url = "https://proxy.example.com/v1"
```

この用途で `[model_providers.openai]` を作りません。`openai`、`ollama`、`lmstudio` は reserved built-in provider ID であり、同名の custom block では上書きできません。

ただし `openai_base_url` は任意の gateway への互換証明ではありません。gateway が独自 token、独自 balance、独自 model alias、独自 support を持つなら、OpenAI route に混ぜず別 provider として表現した方が、障害の owner が明確です。

## 独自 APIキーを使う provider

provider routing は user-level の `~/.codex/config.toml` に置きます。

```toml
model = "EXACT_PROVIDER_MODEL_ID"
model_provider = "company_gateway"

[model_providers.company_gateway]
name = "Company gateway"
base_url = "https://gateway.example.com/v1"
env_key = "COMPANY_GATEWAY_API_KEY"
wire_api = "responses"
```

secret は TOML ではなく environment に渡します。

```bash
export COMPANY_GATEWAY_API_KEY="replace-with-provider-key"
```

`env_key` に書くのは secret の値ではなく**環境変数名**です。terminal で export した後、別の環境から IDE や desktop app を起動すると、その process に variable が届かない場合があります。値を表示せず presence だけ確認します。

```bash
if [ -n "${COMPANY_GATEWAY_API_KEY:-}" ]; then
  echo "provider key is available"
else
  echo "provider key is missing"
fi
```

Base URL の末尾に `/v1` が必要かは provider contract 次第です。すべての service に共通の slash rule はありません。同じ provider account の docs から Base URL と exact model ID を取得してください。

## Provider auth は一つだけ選ぶ

[Alternative model providers の認証説明](https://learn.chatgpt.com/docs/auth#alternative-model-providers) では、次の route が分かれています。

1. `requires_openai_auth = true` は OpenAI authentication を使い、`env_key` を無視します。OpenAI auth を明示的に受ける LLM proxy に適します。
2. `env_key = "PROVIDER_VARIABLE"` は provider 固有 key を環境変数から読みます。
3. 両方を書かない場合、Codex は認証不要 endpoint とみなします。これは管理下の local service に限って使います。

短期 bearer token を取得する gateway には `[model_providers.<id>.auth]` command もあります。ただし command auth は `env_key`、`requires_openai_auth`、experimental bearer token と組み合わせられません。複数 auth を置くと fallback ではなく、どの credential が `401` を起こしたか分からない状態になります。

## Project の `.codex/config.toml` では無視される

trusted project でも、repository が machine-level provider と auth を変更することはできません。OpenAI の [project config 説明](https://learn.chatgpt.com/docs/config-file/config-advanced#project-config-files-codexconfigtoml) では、project layer にある次の key を Codex が無視するとしています。

- `openai_base_url`
- `model_provider`
- `model_providers`

これらを `~/.codex/config.toml` に移します。TOML parse error ではなく、repository が user の code context と credential を別 endpoint へ黙って redirect できないようにする security boundary です。

user config が反映されない場合は、実際の launch command、CLI `--config`、選択中 profile を確認します。Precedence は許可された値の勝敗を決めますが、禁止された project key を有効にはしません。

## 同じ route で最小確認を行う

TOML が parse できても、end-to-end の成功ではありません。`/v1/models` が `200` でも、list endpoint 以外の Responses、auth、streaming、tools は未確認です。

![Codex を同じ route で最小確認し、症状から config、credential、Base URL、model、provider capability の担当を決める表](https://blog.laozhang.ai/posts/ja/codex-config-toml/img/verification-and-errors.webp)

1. 現在の user config を backup し、新しい provider block を最小にする。
2. Provider ID、Base URL、model ID、wire API、credential issuer が一つの service を表すことを確認する。
3. Environment variable が見える同じ process から Codex を起動する。
4. repository や個人情報を含まない短い task、たとえば正確に `ROUTE_OK` と返す依頼を送る。
5. Text が成功した後に、実際に必要な streaming、tool call、long context、web search を個別に確認する。

Plain text 成功だけで「完全互換」と判断しません。Request が意図した provider に届いた後は、config layer を変更し続けても provider account や adapter の不足は直りません。

## Error から次の owner を決める

| 観測結果 | 次に確認する owner | Action |
| --- | --- | --- |
| 以前の provider が使われる | Config layer、profile、launch flag | User config と実際の起動を照合 |
| Environment variable がない | Process environment | Codex を起動する process に渡し、secret は表示しない |
| `401` / `403` | Credential、account、auth scheme | Key issuer に scope と status を確認 |
| `404` / `405` | Base URL、path、wire API | Provider の現行 endpoint contract と比較 |
| Model not found | Model mapping、account access | 同じ account に見える exact model ID を使う |
| Text は成功し、stream/tool が失敗 | Provider capability、adapter | 最小 failing test を保存し、互換性の範囲を限定 |
| Platform cost のみ増える | Login と billing route | `codex login status` と [Codex token usage](https://blog.laozhang.ai/ja/posts/codex-token-usage) を確認 |

Support に渡す evidence は、Codex version、OS、CLI/IDE/desktop、provider ID、Base URL hostname、model ID、`wire_api`、error text、status、request ID、timestamp で十分です。API key、Authorization header、`auth.json`、private code、customer data は除きます。

設定完了の基準は、読み込まれた layer、credential issuer、受信 Base URL、model namespace、失敗時の次 owner を説明できることです。不明点が残るなら field を追加せず、一つの provider、一つの auth source、一つの安全な request に戻します。この小さな route は診断できますが、複数 service の設定を混ぜた「万能 config.toml」は診断できません。

## 参考資料

本文で参照している外部ページを、登場順に並べています。最終更新日：2026-09-01。

- [Advanced Configuration](https://learn.chatgpt.com/docs/config-file/config-advanced) (learn.chatgpt.com)
- [Authentication](https://learn.chatgpt.com/docs/auth) (learn.chatgpt.com)