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

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 と Authentication を基準にしています。Codex の schema は更新されるため、古い設定例より現行の一次資料を優先してください。

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

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

一つの行だけ別サービスを指しているなら、そのまま起動しません。「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キーとサブスクリプション を確認してください。

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 の認証説明 では、次の 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 説明 では、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 は未確認です。

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 を決める

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」は診断できません。