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" / "xhigh" / "max" / "ultra"	推論にかける深さ。高いほど慎重だが遅く、消費も増える。使える段階はモデルとクライアントによるとリファレンスは書いている

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

推論の深さの目安:

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

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

effort(推論の深さ)を変更する 3 つの方法

変更を「どのくらい持続させたいか」で使い分けます。

やりたいこと	方法
恒久的に変える	~/.codex/config.toml の model_reasoning_effort を設定する
1 回だけ変える	codex -c model_reasoning_effort='"high"' "<プロンプト>"
セッション中に変える	/model を実行する

設定リファレンスは、この値を「選んだモデルが公表する推論の深さ。たとえば low、medium、high、xhigh、max、ultra」と説明し、使える段階はモデルとクライアントによると付け加えています(以前のリファレンスにあった minimal は現在は載っていません)。Plan モード用の plan_mode_reasoning_effort と、起動されるエージェント用の agents.default_subagent_reasoning_effort は別のキーです。詳細は Codex CLI で推論の深さ(effort)を変更する方法 にまとめています。

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

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

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"

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

yolo モード(--yolo)は config.toml に書かない

codex --yolo は、公式ドキュメントで --dangerously-bypass-approvals-and-sandbox の別名として記載されているフラグです。承認プロンプトもサンドボックスも通さずにコマンドを実行します。ドキュメントは「使う前に注意してください」と明記しており、--yolo などのフルアクセス設定では Web 検索が既定でライブ結果になるとも書かれています。

これは 1 回の起動で指定するフラグで、config.toml に恒久設定として書くものではありません。設定で近い状態を作るなら approval_policy と sandbox_mode を個別に指定し、使い捨てのコンテナや CI ランナーに限定してください。組み合わせは Codex の承認モードとサンドボックスを使い分ける にまとめています。

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 / xhigh / max / ultra から選ぶ
• codex --profile 名前 で切り替え、profile = "名前" で既定を決める
• 優先順位は「コマンドラインオプション > プロファイル > トップレベル > 既定」

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "本番の設定ファイルは変更できません"
  }
}