Codex CLI config.toml 逆引き：model・推論量・Fast・sandbox・mcp_servers

Codex CLIの ~/.codex/config.toml は、基本値を1つのファイルに置き、用途ごとの差分は ~/.codex/<name>.config.toml(プロファイル)に分け、その場限りの変更は -c key=value で上書きするという3層で運用すると壊れません。この記事は、公式Configuration Referenceのキー名をそのまま使い、筆者が実際に使っている設定ファイルから抜粋したコピペ例を用途別に並べた逆引きです。

エラーが出ているときは先にCodex CLI エラー集を、設定ファイルより先にAGENTS.mdを整えたいときはAGENTS.md 完全ガイドを読んでください。

先に押さえる5点

ファイルの場所と優先順位

公式Config basicsの記載をそのまま整理します。

~/.codex/config.toml            # ユーザー設定(基本)
~/.codex/<name>.config.toml     # プロファイル。--profile <name> で重ねる
<repo>/.codex/config.toml       # プロジェクト設定。trust_level = "trusted" のときだけ読まれる
/etc/codex/config.toml          # システム設定(Unix)

プロジェクト層は「Codex loads project .codex/ layers only when you trust the project」で、信頼していないプロジェクトでは設定・hooks・rulesのすべてが読み飛ばされます。信頼状態は ~/.codex/config.toml の [projects.'<path>'] trust_level = "trusted" に記録され、筆者のファイルにも作業ディレクトリごとに1エントリずつ並んでいました。プロジェクト設定で上書きできないキー(モデルプロバイダ、認証、通知、テレメトリ、プロファイル選択)もあると公式リファレンスに明記されています。

一時的な上書きは -c です。codex --help から引用します。

-c, --config <key=value>
    Override a configuration value that would otherwise be loaded from `~/.codex/config.toml`.
    Use a dotted path (`foo.bar.baz`) to override nested values. The `value` portion is parsed
    as TOML. If it fails to parse as TOML, the raw string is used as a literal.

--enable <feature> / --disable <feature> は -c features.<name>=true/false の短縮形、--strict-config は未知のキーがあればエラーにするフラグです。

用途1: 日常用と深掘り用をプロファイルで切り替える

公式Advanced Configurationによると、プロファイルは ~/.codex/<name>.config.toml に「基本と違う値だけ」を書き、codex --profile <name> で重ねます。筆者が実際に使っている2ファイルをそのまま載せます。

# ~/.codex/daily.config.toml — 日常のコーディング・保守向け
model = "gpt-5.6-terra"
model_reasoning_effort = "medium"
web_search = "cached"

# ~/.codex/deep.config.toml — 難しい監査・最新資料の調査向け
model = "gpt-6-astra"
model_reasoning_effort = "high"
web_search = "live"

codex --profile daily
codex exec --profile deep "review this change"

関連キーは次の通りです(公式リファレンスの値)。

• model_reasoning_effort: minimal / low / medium / high / xhigh
• plan_mode_reasoning_effort: 上に none を加えた値。プランモードだけ別の推論量にできる
• model_reasoning_summary: auto / concise / detailed / none
• web_search: disabled / cached / indexed / live(既定 cached)
• personality: none / friendly / pragmatic
• review_model: /review だけ別モデルにしたいとき
• hide_agent_reasoning: 推論イベントを出力から隠す(筆者は true)

用途2: 推論量と速度(Standard / Fast)を選ぶ

推論量(model_reasoning_effort)は「1つの仕事にどれだけ考えさせるか」、Standard / Fast(service_tier)は「どれだけ速く処理させるか」の設定で、別々に決めます。xhigh にしたから速くなるわけではなく、Fastにしたから浅くなるわけでもありません。high + Fast、medium + Standard のように組み合わせます。

判断は2問に分けます。

1. もっと深く考える必要があるか。 必要なら medium から high、xhigh へ上げる。
2. 待ち時間を短くする価値があるか。 価値があるならStandardからFastへ切り替える。

「難しいからFast」ではありません。難しい仕事なら推論量を上げ、急いでいるならFastです。

推論量の選び方

公式Modelsページの原則は、必要な結果を出せる最も低い推論量を使うことです。高くするほど複雑な計画・比較・確認に強くなる可能性がある一方、応答時間とトークン使用量も増えます。medium は速度と深さのバランスが取れた設定として案内されており、日常作業の基準になります。

括弧内は2026年7月時点のアプリ上の表記です。xhigh は常用する値ではなく、監査のように見落としのコストが高い仕事で時間と使用量を品質に振る設定です。公式のCodex Securityクイックスタートも、最高品質の設定例に xhigh を挙げていました(2026年7月時点、モデルは gpt-5.6-sol)。

上限は失敗コストで決めます。文章の初稿なら多少の不足は次のターンで直せますが、認証変更、データ移行、公開前レビュー、セキュリティ監査は見落としの損失が大きくなります。タスクの見た目の難しさだけでなく、間違えたときの損失を推論量に反映します。結果に不満があるときは、原因で動かすキーを変えます。

• 回答が浅い、見落としがある → 推論量を1段上げる
• 回答は十分だが遅い → Fastを検討する
• 明確な作業なのに重い → 推論量を1段下げる
• 同じ種類の軽作業が大量にある → model で軽いモデルも比較する

config.tomlでは、日常の基準を用途1のdailyプロファイル(medium)に、深掘りをdeepプロファイル(high)に置き、それ以外の段はその場で -c を使います。プランモードだけ深く考えさせたいなら plan_mode_reasoning_effort を別に上げます。対話中は /model からモデルと推論量を変更できます。

codex --profile daily                                              # medium で日常作業
codex exec --profile deep "review this change"                     # high でレビュー
codex exec -c model_reasoning_effort=xhigh "audit the auth flow"   # その場だけ xhigh

StandardとFastの使い分け

Standardを普段の設定にします。バックグラウンドで任せられる、数分の差が成果に影響しない、クレジットを効率よく使いたい、high 以上で既に使用量が増えている、といった場面です。high / xhigh の仕事は待つ前提になりやすいので、Standardと相性がよい組み合わせです。

Fastは、待ち時間が作業のボトルネックになるときに使います。Codexと対話しながら短い修正を何度も回す、UI調整やテスト修正を細かく反復する、障害対応や締切直前で速度に明確な価値がある、エージェントの完了を人が待っていて待機コストが高い、といった場面です。

2026年7月24日時点の公式Speedページでは、Fastは対応モデルの処理を1.5倍速くする代わりに、GPT-5.6ではStandardの2.5倍のChatGPTクレジットを消費すると案内されていました。速さの倍率より消費の倍率が大きいので、常時オンではなく待ち時間を買う設定と考えるのが妥当です。倍率は更新される可能性があるので、使う前にSpeedページで現行の値を確かめてください。Pricingページによれば、クレジット消費はモデル、コンテキスト、推論、ツールでも変わります。なお、この倍率はChatGPTでサインインしてCodexを使う場合の話で、APIキーで使う場合はChatGPTクレジットではなくAPIのトークン料金が適用され、API側のPriority processingは別料金です。

Fastは品質不足の解決策ではありません。結果が弱いときにFastへ変えても、待ち時間が短くなるだけです。

切り替えはセッション内なら /fast です。

/fast on
/fast off
/fast status

継続的にFastを既定にする場合、公式Speedページは config.toml に次の設定を案内していました。

service_tier = "fast"

[features]
fast_mode = true

常時にする前に、数日だけ /fast on で試し、実際に待ち時間がボトルネックになっているかを確かめるのがおすすめです。

用途3: MCPサーバーを追加する

stdioとstreamable HTTPの2形式です。公式MCPページの例を、フィールド名を変えずに最小化しました。

# stdio(ローカルプロセス)
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 10     # 既定 10
tool_timeout_sec = 60        # 既定 60
enabled = true
required = false             # true にすると起動失敗でセッションが作れない

[mcp_servers.context7.env]
MY_VAR = "value"

# streamable HTTP(リモート)
[mcp_servers.docs]
url = "https://developers.openai.com/mcp"
# bearer_token_env_var = "MY_TOKEN_VAR"   # 環境変数からBearerを読む
# auth = "oauth"                          # OAuthを使う場合。codex mcp login <name>

コマンドラインからも同じ設定を追加できます。codex mcp add --help(0.144.1)の書式は次の通りです。

codex mcp add <NAME> (--url <URL> | -- <COMMAND>...)
codex mcp add ctx7 --env API_KEY=... -- npx -y @upstash/context7-mcp
codex mcp add docs --url https://developers.openai.com/mcp
codex mcp list          # 一覧(Status / Auth 列あり)
codex mcp login docs    # OAuth

ツール単位の制御も用意されています。

[mcp_servers.context7]
enabled_tools = ["resolve-library-id", "get-library-docs"]   # 許可リスト
disabled_tools = []                                          # 許可後に除外
default_tools_approval_mode = "prompt"

[mcp_servers.context7.tools.get-library-docs]
approval_mode = "approve"
output_token_limit = 30000

Windowsでは、筆者の設定はすべて command に実行ファイルのフルパスを書いています。npx のようなシェル解決前提のコマンドで「program not found」になったら、フルパスか cwd の指定を試します。

用途4: 権限を絞る

公式Agent approvals & securityとAdvanced Configurationの例を組み合わせた、読み取り専用の対話設定です。

# 読み取り専用で相談だけしたい
approval_policy = "on-request"
sandbox_mode = "read-only"

# 作業ディレクトリだけ書込可、ネットワークは必要な時だけ
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false           # 既定 false。npm install 等が要るなら true
writable_roots = []              # 追加で書き込みを許す場所
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

approval_policy の値は on-request / never と、細かく制御する granular テーブルです。公式は「Codex and ChatGPT Work no longer support approval_policy = “untrusted”」としています。0.144.1の codex --help にはまだ untrusted が候補として残っていますが、設定に書くのは避けます。

# granular の例(公式 Advanced Configuration より)
approval_policy = { granular = {
  sandbox_approval = true,
  rules = true,
  mcp_elicitations = true,
  request_permissions = false,
  skill_approval = false
} }

子プロセスに渡す環境変数も絞れます。公式の説明では、名前に KEY / SECRET / TOKEN を含む変数は既定で除外され、ignore_default_excludes = false でその既定除外をカスタムフィルタの前に適用します。

[shell_environment_policy]
inherit = "core"                 # all / core / none
ignore_default_excludes = false
set = { MY_FLAG = "1" }

[shell_environment_policy.filters]
"AWS_*" = "exclude"
"AZURE_*" = "exclude"

Windowsネイティブで動かす場合は、サンドボックスの実装を選びます。

[windows]
sandbox = "elevated"             # 推奨。動かない環境では "unelevated"
# sandbox_private_desktop = true # 既定 true

全部外す sandbox_mode = "danger-full-access" と --dangerously-bypass-approvals-and-sandbox は、公式・--help ともに「外部で隔離済みの環境専用」と警告しています。

用途5: ターン完了を通知する(notify)

notify は外部プログラムを起動するフックで、公式Advanced Configurationの説明では現在 agent-turn-complete イベントに対応しています。配列の先頭がプログラム、以降が引数で、最後にJSONが1引数として渡されます。

notify = ["python3", "/path/to/notify.py"]

JSONに含まれるキーは type、thread-id、turn-id、cwd、input-messages、last-assistant-message です。筆者環境では、デスクトップアプリが自動で notify = ["<computer-use の exe>", "turn-ended"] を書き込んでいました。自分で設定するときは、このキーをアプリ側が上書きする可能性を頭に入れておきます。

TUI側の通知は notify とは別に [tui] で制御します。

[tui]
notifications = true                 # または ["agent-turn-complete", ...]
notification_method = "auto"         # auto / osc9 / bel
notification_condition = "unfocused" # unfocused / always

用途6: プロジェクトごとの設定と機能フラグ

リポジトリ直下の .codex/config.toml に、そのプロジェクトだけの値を置けます(信頼済みプロジェクトのみ)。

# <repo>/.codex/config.toml
model_reasoning_effort = "high"
project_doc_max_bytes = 65536        # AGENTS.md から読む上限
project_doc_fallback_filenames = ["CLAUDE.md"]   # AGENTS.md が無いときの代替

機能フラグは [features] テーブルです。筆者の設定では multi_agent = true、memories = true を有効にしています。公式リファレンスに載っている主なもの:

• features.hooks: hooks.json またはインライン [hooks] のライフサイクルフック
• features.multi_agent: マルチエージェント(既定 on)
• features.goals: ゴールの永続化と継続(既定 on)
• features.unified_exec: PTYベースの統合exec(Windows以外は既定 on)
• features.network_proxy: サンドボックス内コマンド用のネットワークプロキシ(既定 off)。domains で allow / deny を指定
• features.prevent_idle_sleep: ターン中のスリープ抑止(既定 off)

codex features list      # 既知の機能とステージ・有効状態
codex features enable hooks
codex --enable hooks     # 一時的に有効化(= -c features.hooks=true)

逆引き早見表

公式リファレンスにはJSONスキーマ(config-schema.json)へのリンクもあり、エディタで補完・検証したい場合はそちらを参照するよう案内されています。

版による差分に注意します。 筆者環境の0.144.1と公式資料(0.154.0相当)で、approval_policy の untrusted の扱いが違いました。CLIの --help にある値が公式で廃止済みということがあるので、設定を書くときは --help より公式Configuration Referenceを正とし、--strict-config で未知キーを検出する運用が安全です。

まとめ

• 3層で運用する: ~/.codex/config.toml(基本)、<name>.config.toml(用途別の差分)、-c(その場限り)
• プロファイルは別ファイル方式。[profiles.x] は0.134.0以降読まれない
• 推論量(model_reasoning_effort)と速度(service_tier)は別々に決める。基準は medium + Standard、深さが足りなければ推論量を上げ、待ち時間が問題ならFast
• MCPは [mcp_servers.<id>]。stdioは command/args、HTTPは url。起動10秒・ツール60秒が既定で、required = true は起動失敗を致命化する
• 権限は approval_policy(on-request / never)と sandbox_mode の2キー。workspace-write でもネットは既定で閉じている
• notify はデスクトップアプリが上書きすることがある。[tui] の通知とは別物

筆者の設定ファイルで一番効いていたのは、凝ったキーではなく「daily と deep の2プロファイルを別ファイルに分けた」ことでした。基本設定を触らずにモデルと推論量だけ切り替えられる——config.tomlで最初に作るべきはその2ファイルです。