Codex CLI の config.toml でモデル・推論の深さ・プロファイルを切り替える

Codex CLI の挙動は ~/.codex/config.toml で決まります。モデル、推論の深さ、承認ポリシー、サンドボックス、MCP サーバーなど、ほぼすべての設定がここに集まっています。この記事では、日常的に触ることになる項目に絞って、書き方と使い分けを整理します。

config.toml の場所と基本構造

# ~/.codex/config.toml

model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

TOML 形式で、トップレベルに既定値、[profiles.名前] や [mcp_servers.名前] のようなテーブルで個別の設定を書きます。ファイルがなければ作成してください。

モデルと推論の深さ

キー	値の例	意味
model	"gpt-5-codex" など	使用するモデル。利用可能な名前は /model で確認する
model_reasoning_effort	"low" / "medium" / "high"	推論にかける深さ。高いほど慎重だが遅く、消費も増える

モデル名はリリースごとに変わります。config.toml に書いたモデルが使えなくなった場合はエラーになるので、/model で現在の選択肢を確認して書き換えてください。

推論の深さの目安:

• low: 定型的な修正、コメント追加、小さなリファクタリング
• medium: 日常の開発全般
• high: 設計判断、難しいバグの調査、大規模な変更

対話中は /model からモデルと推論の深さを一時的に切り替えられます。config.toml の値は次回起動時の既定です。

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

同じ設定を毎回オプションで指定するのではなく、プロファイルとして定義します。

model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profiles.quick]
model_reasoning_effort = "low"
approval_policy = "on-failure"

[profiles.deep]
model_reasoning_effort = "high"
approval_policy = "on-request"

[profiles.readonly]
sandbox_mode = "read-only"
approval_policy = "on-request"

codex --profile quick "typo を直して"
codex --profile deep "認証周りの設計を見直して"
codex --profile readonly "この機能の呼び出し元を洗い出して"

プロファイルに書かなかったキーは、トップレベルの値が使われます。承認とサンドボックスの選び方は approval mode と sandbox 設定の違い を参照してください。

既定のプロファイルを指定する

profile = "quick"

と書くと、--profile を付けないときに quick が使われます。

設定の優先順位

同じ項目が複数の場所で指定された場合、次の順で優先されます。

1. コマンドラインオプション(--model、--sandbox など)
2. --profile で選んだプロファイルの値
3. config.toml のトップレベルの値
4. Codex の組み込み既定値

「オプション > プロファイル > トップレベル > 既定」と覚えておけば、意図しない値が使われたときに原因を追えます。

その他のよく使う項目

# 起動時に読み込む AGENTS.md の合計サイズ上限(バイト)
project_doc_max_bytes = 32768

# 通知(対応する環境で、タスク完了時にデスクトップ通知)
notify = ["notify-send", "Codex"]

# 履歴の保存
[history]
persistence = "save-all"

キー名や対応状況はバージョンによって変わります。設定が効かない場合は、公式ドキュメントの設定リファレンスで現在の名前を確認してください。

MCP サーバーの設定

MCP サーバーも config.toml の [mcp_servers.名前] に書きます。設定例と接続確認の方法は Codex CLI に MCP サーバーを設定する にまとめています。

設定を確認する

対話中に /status を実行すると、現在のモデル、推論の深さ、承認ポリシー、サンドボックス、読み込まれた AGENTS.md が表示されます。config.toml を編集した後は、この画面で反映を確認する習慣をつけてください。

まとめ

• 設定は ~/.codex/config.toml。トップレベルに既定値、[profiles.名前] で用途別の設定を書く
• model は /model で確認できる名前を書き、model_reasoning_effort は low / medium / high で使い分ける
• codex --profile 名前 で切り替え、profile = "名前" で既定を決める
• 優先順位は「コマンドラインオプション > プロファイル > トップレベル > 既定」