Codexのconfig.tomlの設定方法：カスタムAPI、プロキシ、よくあるエラー

Codexの設定は1つのファイルconfig.tomlに保存されています。使用するモデル、呼び出すAPI、エージェントに確認なしで許可する操作の範囲などを指定できます。2026年には書式が何度か変更されており、年初の古いガイドに載っている設定ではCodexが起動しなくなることがあります。

このガイドでは、まず動作する設定例を紹介し、その後、多くの人が変更する項目であるプロファイル、プロジェクト設定、サンドボックス、プロキシについて説明します。最後に、よくあるエラーとその意味を一覧にしました。2026年10月19日にOpenAIのドキュメントと照合し、Codex CLI 0.162.1で動作を確認しています。例ではプロバイダーにAIHubMixを使っていますが、OpenAI Responses APIに対応するゲートウェイなら同様に使えます。

要点

ファイルの場所は~/.codex/config.tomlです。WindowsではC:\Users\<you>\.codex\config.tomlになります。
カスタムプロバイダーにはbase_url、wire_api = "responses"、env_keyが必要です。APIキーは環境変数に設定します。
プロファイルは独立したファイル~/.codex/<name>.config.tomlになり、--profile <name>で選択します。
リポジトリの.codex/config.tomlは、信頼済みプロジェクトでのみ有効で、プロバイダーは変更できません。
編集するたびにCodexを再起動してください。設定ファイルは起動時にのみ読み込まれます。

config.tomlの場所

メインの設定は~/.codex/config.tomlにあります。CLIとIDE拡張機能の両方がこのファイルを読み込みます。まだファイルがなければ作成してください。

ほかにも、設定を追加できる場所が2つあります。

プロファイルファイル（~/.codex/<name>.config.toml）。--profile <name>を付けてCodexを起動したときにのみ使用されます。
プロジェクトファイル（リポジトリ内の.codex/config.toml）。チームで共有する設定に使います。

Windows上のWSL2でCodexを実行する場合、Windows側ではなくLinuxのホームにある/home/<you>/.codex/config.tomlを読み込みます。CODEX_HOMEが設定されている場合は、~/.codexの代わりにそのフォルダーを使います。

最小限の動作する設定

次の~/.codex/config.tomlの完全な設定例では、CodexのリクエストをAIHubMixに送信します。

model = "gpt-6-sol"
model_provider = "aihubmix"
model_reasoning_effort = "high"

[model_providers.aihubmix]
name = "AIHubMix"
base_url = "https://aihubmix.com/v1"
wire_api = "responses"
env_key = "AIHUBMIX_API_KEY"

modelは呼び出すモデルID、model_reasoning_effortはデフォルトの推論レベルです。
model_providerは[model_providers.<name>]にある名前と一致させる必要があります。openai、ollama、lmstudioはCodex組み込みのプロバイダー用に予約されているため、使わないでください。
base_urlはプロバイダーのAPIアドレスです。現在、Codexが受け付ける値はwire_api = "responses"のみです。
env_keyには環境変数の名前を指定します。APIキーそのものではありません。

続いて、AIHubMixのコンソールで取得したキーを使って、その環境変数を設定します。

# macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export AIHUBMIX_API_KEY=sk-...

# Windows PowerShell: takes effect in new terminals
setx AIHUBMIX_API_KEY "sk-..."

新しいターミナルからcodexを起動し、何か質問してみてください。回答が返ってくれば、プロバイダーは動作しています。Codexにログインしているかどうかは関係ありません。codex loginで使うキーがカスタムプロバイダーに送信されることはありません。

プロファイル：設定ごとにファイルを1つ

プロファイルには、より深い推論やコードレビュー向けの読み取り専用サンドボックスなど、メイン設定と異なる項目だけを記述します。各プロファイルはconfig.tomlと同じ場所に置く独立したファイルで、キーは最上位に記述します。

# ~/.codex/review.config.toml
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex --profile review

これはCodex 0.134.0で変更されました。古いガイドでは、config.toml内に[profiles.review]テーブルを作り、profile = "review"で選択する方法が紹介されています。現在のCodexは、この選択設定があると起動を拒否します。[profiles.review]テーブルだけが残っている場合は、メッセージなしで無視されるため、その設定はいつの間にか効かなくなります。移行するには、各テーブルのキーを~/.codex/<name>.config.tomlに移し、テーブルとprofile = ...の行を削除してください。詳しくはOpenAIの高度な設定ガイドを参照してください。

プロジェクト設定：.codex/config.toml

リポジトリに.codex/config.tomlを置くと、チームでデフォルトのモデル、推論レベル、サンドボックスモードを共有できます。Codexがこのファイルを読み込むのは、自分の~/.codex/config.tomlで信頼済みとマークしたプロジェクトのみです。

[projects."/Users/you/code/my-app"]
trust_level = "trusted"

プロジェクトファイルでは、リクエストの送信先は変更できません。model_provider、model_providers、openai_base_url、profile、notifyなど、ほかにもいくつかのキーは無視され、その際に警告が表示されます。プロバイダーの設定は~/.codex/config.tomlに記述してください。プロジェクト側でモデルを選ぶことはできますが、リクエストは自分のプロバイダーに送信されます。

どの設定が優先されるか

同じキーが複数の場所に設定されている場合、OpenAIの設定の基本に記載されている優先順位は、上位から次のとおりです。

コマンドラインフラグ（-cによる上書きを含む）
プロジェクトの.codex/config.toml
--profileで選択したプロファイル
自分の~/.codex/config.toml
システム設定/etc/codex/config.toml
Codexの組み込みデフォルト設定

プロジェクトファイルはプロファイルより優先される点に注意してください。プロファイルの設定が効かないように見える場合は、リポジトリの.codex/config.tomlで同じキーが設定されていないか確認してください。

1回の実行だけ設定を変更するには、-cを使います。

codex -c model_reasoning_effort=high

サンドボックスと承認

Codexが自律的に実行できる範囲は、2つのキーで制御します。sandbox_modeはコマンドが操作できる対象を指定し、approval_policyはCodexがいつ確認を求めるかを指定します。

sandbox_mode	コマンドが実行できる操作
read-only	ファイルの読み取り。これを超える操作には承認が必要
workspace-write	プロジェクトフォルダーと一時フォルダーへの書き込み
danger-full-access	サンドボックスなしで、あらゆる操作が可能

approval_policy	Codexが確認を求めるタイミング
on-request	サンドボックスの制限を超える必要があるとき
never	確認を求めない。ブロックされたコマンドは失敗する

sandbox_mode = "workspace-write"
approval_policy = "on-request"

[sandbox_workspace_write]
network_access = true   # off by default

この2つは独立しています。neverにすると確認は求められなくなりますが、サンドボックスの制限は緩和されません。workspace-writeでは、network_access = trueを設定するまでコマンドからネットワークにアクセスできません。

プロキシ経由での利用

Codexにはconfig.tomlでプロキシを設定する項目がありません。標準の環境変数を使います。

export HTTPS_PROXY=http://127.0.0.1:7890   # your proxy address
export NO_PROXY=localhost,127.0.0.1

OpenAIのドキュメントには記載がないため、Codex 0.162.1で動作を確認しました。カスタムプロバイダーへのリクエストを含め、リクエストはHTTPS_PROXY（またはALL_PROXY）経由で送信され、NO_PROXYに指定したホストには直接接続しました。PACファイルには対応していないため、プロキシアドレスを直接入力してください。会社のプロキシが独自のルート証明書を使用している場合は、環境変数リファレンスの説明に従ってCODEX_CA_CERTIFICATEにその証明書を指定してください。

/modelに表示するモデルを増やす

/modelのモデル選択メニューに表示されるのは、OpenAIのモデルのみです。ここからGLM、Claude、Gemini、DeepSeekのモデルを選ぶには、モデルカタログを追加します。モデルカタログは、最上位のmodel_catalog_jsonキーで指定するJSONファイルです。このキーは最初の[table]行より前に記述してください。そうしないとTOMLではテーブルの一部として扱われ、Codexに無視されます。

カタログを追加すると組み込みリストが置き換わります。また各エントリーには多くのフィールドが必要なため、手書きではなく生成するのがおすすめです。AIHubMix Codex CLIガイドでは、AIHubMixの上位30モデルをもとにカタログを生成するスクリプトを紹介しています。デスクトップアプリのモデル選択メニューには、カスタムモデルが表示されない場合があります（openai/codex#19694）。その場合はターミナルでモデルを切り替えてください。

よくあるエラーとその意味

以下は、それぞれの設定ミスについてCodex 0.162.1が表示したメッセージです。

legacy profile = "..." config is no longer supported
config.tomlに古いprofile = "..."の行が残っています。上記の説明に従って、プロファイルを独立したファイルに移してください。古い[profiles.x]テーブルがある状態で--profile xを実行すると、--profile x cannot be used while ... contains legacy ... configという同様のエラーが表示されます。

wire_api = "chat" is no longer supported
CodexはChat Completions APIに対応しなくなりました。wire_api = "responses"に変更してください。Chat Completionsしか提供していないプロバイダーは、変換プロキシなしでは動作しません。

model_providers contains reserved built-in provider IDs
プロバイダー名にopenai、ollama、lmstudioを指定しています。テーブル名とmodel_providerを別の名前に変更してください。

approval_policy = "untrusted" is no longer supported
この行を削除するか、on-requestを指定してください。

Missing environment variable: AIHUBMIX_API_KEY
env_keyで指定した変数が、Codexを起動したターミナルで設定されていません。新しいターミナルを開くか、source ~/.zshrcを実行してから、Codexを再起動してください。

数行の「Reconnecting...」の後に401 Unauthorizedが表示される
キーを付けずにリクエストが送信されました。プロバイダーのテーブルにenv_keyがあるか確認してください。auth.jsonに保存されたログイン情報は、カスタムプロバイダーには使われません。

Model metadata for ... not found. Defaulting to fallback metadata
そのモデルの組み込み設定がCodexにありません。OpenAI以外のモデルでは通常のことです。リクエストは引き続き動作します。適切な設定を使い、モデルを/modelに表示するには、モデルカタログを追加してください。

Ignored unsupported project-local config keys
リポジトリの.codex/config.tomlに、自分の設定ファイルでのみ有効なキー（通常はmodel_provider）が指定されています。~/.codex/config.tomlに移してください。

missing field base_instructions
モデルカタログのエントリーに必須フィールドがないため、Codexがファイル全体を拒否しています。手動で編集せず、スクリプトを使ってカタログを再生成してください。

設定が反映されないとき

編集後にCodexを再起動してください。
最上位のキーが最初の[table]行より前にあることを確認してください。
リポジトリの.codex/config.tomlを確認してください。プロファイルより優先されます。
古い[profiles.x]テーブルが残っていないか確認してください。
codex doctorを実行してください。インストール、設定、ログイン状態を確認できます。

OpenAI、Anthropic、Google、Zhipu、DeepSeekなどのモデルを1つのキーでCodexから使いたい場合、AIHubMixではhttps://aihubmix.com/v1でResponses API経由のモデルを提供しています。まずは上記の最小構成から始め、/modelでモデルを切り替えたくなったらモデルカタログを追加してください。

よくある質問

Codexのconfig.tomlファイルはどこにありますか？
macOSとLinuxでは~/.codex/config.toml、WindowsではC:\Users<you>.codex\config.tomlにあります。CODEX_HOMEが設定されている場合は、そのフォルダーにあります。

config.tomlを変更した後、Codexを再起動する必要がありますか？
はい。Codexは起動時にファイルを読み込むため、ターミナルセッションまたはアプリを終了して、再度開いてください。

Codexに「legacy profile config is no longer supported」と表示されるのはなぜですか？
Codex 0.134.0では、config.toml内で定義するプロファイルが廃止されました。各プロファイルを~/.codex/name.config.tomlに移し、古い行を削除してから、--profile nameを指定してCodexを起動してください。

wire_api = "chat"は引き続き使えますか？
いいえ。Codexが受け付けるのはwire_api = "responses"のみです。Chat Completionsのみをサポートするプロバイダーを使うには、Responses APIに変換するプロキシが必要です。

Codexにログインしているのに、カスタムプロバイダーから401が返されるのはなぜですか？
auth.jsonのログインキーはカスタムプロバイダーに送信されません。プロバイダーテーブルにenv_keyを追加し、ターミナルでその環境変数を設定してください。

CodexはHTTPS_PROXYを使用しますか？
はい。Codex 0.162.1でのテストでは、リクエストはHTTPS_PROXY経由で送信され、NO_PROXYに記載されたホストは経由しませんでした。PACファイルはサポートされていません。

プロジェクトの.codex/config.tomlでmodel_providerが無視されるのはなぜですか？
プロジェクトファイルではリクエストの送信先を変更できないため、リポジトリから通信先をリダイレクトすることはできません。プロバイダーは~/.codex/config.tomlに設定してください。プロジェクトファイルでは引き続きモデルを設定できます。

出典

設定の基本、OpenAI
高度な設定、OpenAI
設定リファレンス、OpenAI
Codex CLI統合ガイド、AIHubMix
Codex CLIプロキシ設定：SOCKS、HTTP、企業ネットワーク、Daniel Vaughan