Codex の設定ファイル config.toml の書き方と推奨設定

config.toml は Codex の挙動を恒久化する設定ファイル

config.toml は、Codex の動作を毎回のコマンドではなくファイルで決めておくための設定ファイルだ。CLI で --model や --sandbox のようなフラグを打つと、その指定はそのコマンド一回かぎりで終わる。これに対して config.toml に書いた値は、起動のたびに読み込まれるため、同じ設定を打ち直す必要がなくなる。ファイルの置き場所は用途によって分かれている。利用者ごとの設定は ~/.codex/config.toml に置き、これがもっとも一般的だ。リポジトリ単位で設定を上書きしたい場合は、プロジェクト直下の .codex/config.toml を使うが、これは信頼済みとして扱われたプロジェクトでのみ読み込まれる。Unix 系では組織全体の既定として /etc/codex/config.toml も使える。書式は TOML で、キー = 値 の単純な行と、[テーブル名] で始まるまとまりからできている。IDE 拡張から編集する場合は、歯車アイコンから「Codex Settings > Open config.toml」を選べば同じファイルが開き、CLI と拡張で設定を共有できる（出典: https://developers.openai.com/codex/config-basic）。

CLI フラグと config.toml は対立するものではなく、役割が違う。フラグは「いまこの一回だけ挙動を変えたい」ときに使い、config.toml は「いつもこうしておきたい」という既定値を書く場所だ。たとえば普段は安全側の設定で起動しておき、難しい変更のときだけフラグで思考を深める、といった使い分けが自然にできる。まずは普段の作業に合う既定値を config.toml に固定し、例外をフラグで足していくと、設定が散らからずに済む。

設定が適用される優先順位

config.toml を使ううえで先に押さえておきたいのが、複数の設定源がぶつかったときにどれが優先されるかという順序だ。Codex は設定を一か所だけでなく、いくつかの階層から読み込んでマージする。たとえば普段は ~/.codex/config.toml の値で動かしつつ、特定のリポジトリだけ別のサンドボックスにしたい、あるいは一時的にモデルだけ変えたい、といった使い分けがこの仕組みで成り立つ。どの値が最終的に効くのかを把握していないと、「config.toml に書いたのに反映されない」という混乱につながりやすい。優先順位は、高いものから順に次のとおりだ。

1. CLI フラグおよび --config による直接の上書き（その場かぎりで最優先）
2. プロジェクトの .codex/config.toml（作業ディレクトリに近いものが優先）
3. --profile で選んだプロファイルの設定
4. 利用者ごとの ~/.codex/config.toml
5. システム全体の /etc/codex/config.toml（Unix 系）
6. Codex に組み込まれた既定値

この並びを踏まえると、恒久的に効かせたい設定は ~/.codex/config.toml に、リポジトリ固有の事情は .codex/config.toml に、その場の例外は CLI フラグに、と書き分けるのが基本になる。逆に、フラグで毎回上書きしている設定があるなら、それは config.toml に移して既定にしてしまうほうが手数は減る（出典: https://developers.openai.com/codex/config-basic）。

まず押さえる主要キー

config.toml には多くのキーがあるが、最初に効果を実感しやすいのは、モデル・推論レベル・承認・サンドボックスの四つだ。この四つは、Codex が「どのモデルで」「どれだけ考え」「どこまで自分で実行し」「どこまでファイルやネットワークに触れるか」を決める中心的な設定で、CLI のフラグ --model や --sandbox に対応する内容を恒久化したものにあたる。逆に言えば、この四つを config.toml に書いておけば、毎回フラグを足さなくても意図した挙動で起動できる。以下では、それぞれのキー名と取り得る値を整理する。値は文字列で囲むものが多いため、TOML の書式に沿ってダブルクォートを忘れないようにしたい。

model — 使うモデルを固定する

model は、Codex が既定で使うモデルを指定するキーだ。たとえば model = "gpt-5.5" と書けば、起動のたびに毎回そのモデルが選ばれる。どのプロバイダのモデルを使うかは model_provider で切り替えられ、既定は "openai" だ。普段使うモデルが決まっているなら、ここに書いておくのが最も手軽な固定方法になる（出典: https://developers.openai.com/codex/config-reference）。

model_reasoning_effort — 思考の深さを調整する

model_reasoning_effort は、モデルがどれだけ考えてから答えるかの度合いを決めるキーで、"minimal"・"low"・"medium"・"high"・"xhigh" から選ぶ。深くするほど難しい変更での精度は上がるが、その分だけ応答は遅く、消費も増える。あわせて model_reasoning_summary を "auto"・"concise"・"detailed"・"none" で設定すると、思考の要約をどの程度表示するかを調整できる（出典: https://developers.openai.com/codex/config-reference）。

approval_policy — 承認を求める粒度を決める

approval_policy は、Codex がコマンドを実行する前にどこまで人間の承認を求めるかを決める。"untrusted" は信頼済み以外の操作で都度確認し、"on-request" は必要なときにモデル側から承認を求め、"never" は確認を挟まずに進む。確認の手数と安全性のバランスを取るキーで、より細かく制御したい場合はテーブル形式での指定もできる（出典: https://developers.openai.com/codex/config-reference）。

sandbox_mode — 書き込みとネットワークの範囲

sandbox_mode は、Codex が触れてよい範囲を決める。"read-only" は読み取りのみ、"workspace-write" は作業ディレクトリ内への書き込みを許可、"danger-full-access" は制限を外す。"workspace-write" のときは、[sandbox_workspace_write] テーブルの network_access を true にしない限り、外部ネットワークへのアクセスは既定で遮断される（出典: https://developers.openai.com/codex/config-reference）。

用途で設定を切り替えるプロファイル

一つの設定で全部の作業をまかなおうとすると、どこかで無理が出る。レビューのときは読み取り専用で慎重に、定型作業のときは確認を減らして手早く、というように、場面ごとに最適な設定は変わるからだ。Codex はこの切り替えを「プロファイル」で実現する。[profiles.<名前>] というテーブルに、その用途向けのキーをまとめて書いておき、起動時に --profile <名前> で選ぶだけで、その一式が適用される。プロファイルの設定は、優先順位のうえでは利用者の config.toml より上、CLI フラグより下に位置づけられるため、土台の設定を活かしつつ必要な部分だけ上書きできる。たとえば、慎重に確認したいレビュー用のプロファイルは次のように書ける。

[profiles.review]
model_reasoning_effort = "high"
approval_policy = "untrusted"
sandbox_mode = "read-only"

これを codex --profile review で呼び出せば、普段の設定はそのままに、レビューのあいだだけ深い思考・厳しい承認・読み取り専用に切り替わる。プロファイルは設定ディレクトリ（環境変数 CODEX_HOME で変更でき、既定は ~/.codex）のもとで管理されるため、レビュー用・調査用・実装用といった複数の用途を並行して持っておける。よく使う組み合わせを名前付きで残しておくと、毎回フラグを並べる手間が減り、設定の意図もチームで共有しやすくなる（出典: https://developers.openai.com/codex/config-reference）。

外部ツールをつなぐ mcp_servers と通知まわり

config.toml は、モデルやサンドボックスといった基本動作だけでなく、Codex を外部のツールや環境となじませる設定も担う。代表的なのが [mcp_servers.<id>] テーブルで、ここに起動コマンドや引数、環境変数を書いておくと、その外部ツールを Codex から呼び出せるようになる。書き方は次のように、command と args を中心に組み立てる。

[mcp_servers.example]
command = "npx"
args = ["-y", "example-mcp-server"]
env = { EXAMPLE_TOKEN = "..." }

env に渡す資格情報はパスワードと同じ機密として扱い、共有リポジトリにそのまま書き込まないよう注意する。このほか、長い処理が終わったときに知らせる notify（実行するコマンドを配列で指定）、ソース参照時に開くエディタを選ぶ file_opener（"vscode"・"cursor" など）、思考イベントの表示を抑える hide_agent_reasoning、会話履歴の保存方針を決める history.persistence（"save-all" か "none"）といったキーで、日々の使い勝手を細かく調整できる。いきなり全部をいじる必要はなく、不便を感じたものから一つずつ足していくのが現実的だ（出典: https://developers.openai.com/codex/config-reference）。

迷ったときの推奨設定

キーの数は多いが、最初から全部を埋める必要はない。多くの利用者にとって出発点になるのは、普段使うモデルを固定し、思考の深さを中庸に保ち、承認とサンドボックスを「手早いが無謀ではない」あたりに置く構成だ。具体的には、次のような ~/.codex/config.toml から始めるとバランスが取りやすい。

# ~/.codex/config.toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

この構成の狙いは次のとおりだ。

1. model を固定して、起動ごとにモデルを選び直す手間をなくす。
2. model_reasoning_effort = "medium" で、速度と精度のバランスを既定にする。難所だけプロファイルや CLI フラグで "high" に上げる。
3. approval_policy = "on-request" で、必要なときだけ確認を挟み、定型作業を止めすぎない。
4. sandbox_mode = "workspace-write" と network_access = false で、作業ディレクトリ内には書けるが外部通信は既定で遮断し、不用意なアクセスを防ぐ。

ここを土台にしておき、レビューや無人寄りの作業はプロファイルで切り替えると、安全側の既定を保ちながら場面ごとに最適化できる。設定を変えたら、まず小さなタスクで意図どおり動くかを一度確かめておくと安心だ（出典: https://developers.openai.com/codex/config-basic）。

まとめ — config.toml は「いつもの設定」を一枚に集める場所

Codex の config.toml は、毎回のフラグ入力を置き換える恒久的な設定ファイルだ。置き場所は利用者向けの ~/.codex/config.toml が基本で、プロジェクト固有の事情は .codex/config.toml、その場の例外は CLI フラグ、と優先順位に沿って書き分ければ、設定が「反映されない」混乱を避けられる。まず固定すべきは、model・model_reasoning_effort・approval_policy・sandbox_mode の四つで、これだけで Codex の挙動の大枠が決まる。

用途ごとの切り替えはプロファイル、外部ツール連携は mcp_servers、通知やエディタ連携は専用キーで補える。迷ったら本記事の推奨設定から始め、慣れるにつれて自分の作業に合わせて削り足していくのが、設定ファイルと長くつき合うコツになる。

出典

• Basic configuration – Codex（OpenAI Developers）
• Configuration reference – Codex（OpenAI Developers）
• Advanced configuration – Codex（OpenAI Developers）
• openai/codex（GitHub）