Codex の config.toml 設定ガイド：反映順序と安全な直し方

Codex を起動できた後に必要なのは、設定項目を増やすことではなく、どのレイヤーが実際に動作を決めているかを把握することです。config.toml の巨大なサンプルをそのまま貼り付けると、model だけを変えたつもりでも、sandbox、approval、provider、web access、MCP まで同時に変わることがあります。

まず個人用の既定値は ~/.codex/config.toml、リポジトリ固有の値は trusted project 内の .codex/config.toml と分けます。繰り返し使う作業モードは別の profile ファイル、一度だけ試す値は CLI override が向いています。CLI と IDE extension は同じ設定レイヤーを共有します。場所と基本動作は OpenAI の Config basics で確認できます。

編集前には対象ファイルだけをバックアップしてください。1つの table を直すために ~/.codex 全体を削除すると、認証状態、profiles、rules など正常な情報まで失う可能性があります。

「どのファイルか」より先に「誰の設定か」を決める

Codex の通常設定は、優先度の高い順に次のように解決されます。

1. CLI flag と --config override
2. trusted project の .codex/config.toml（現在のディレクトリに近いものが優先）
3. --profile で選択した profile ファイル
4. user config の ~/.codex/config.toml
5. Unix の /etc/codex/config.toml（存在する場合）
6. built-in default

公式の Configuration precedence にこの順序が示されています。user config を直しても変化しない場合、保存ミスとは限りません。上位の project、profile、CLI が値を上書きしている可能性があります。

設定の置き場所は次の基準で決めると整理できます。

ただし project config では、machine-local な provider、auth、profile 選択、notification、telemetry 系のキーを上書きできません。現在の対象には model_provider、model_providers、profile、otel などが含まれます。正確な一覧は最新の Configuration reference を使い、該当キーは user レベルへ置きます。

最初のファイルは短くてよい

個人設定の出発点は、たとえば次の程度です。

toml
model = "gpt-5.6"
model_reasoning_effort = "high"

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

サンプルの model ID が自分の client と account で利用できることは別途確認してください。model 名は更新されるため、永久的な推奨値ではありません。既定動作で問題がないキーは書かない方が、将来の update 後も原因を追いやすくなります。

approval_policy は「いつ承認を求めるか」、sandbox_mode は「command がどこまで触れられるか」を制御します。別々の安全装置です。OpenAI は workspace-write と on-request を、より低リスクな local automation の組み合わせとして説明しています。danger-full-access と never は両方の境界を外すため、通常の既定値には適しません。現在の定義は Sandbox の Configure defaults にあります。

web access も別の判断です。現在の top-level web_search は cached、indexed、live、disabled を受け取ります。古い [features] の web-search toggle は deprecated です。過去の sample が parse できることと、現行の推奨形式であることは同じではありません。

Profile は main config の table ではない

read-only の確認作業を繰り返すなら、別ファイルに差分だけを書きます。

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

bash
codex --profile read-review

profile は user config の上に重なり、さらに project や CLI が上書きできます。Codex 0.134.0 以降、--profile は main config 内の [profiles.read-review] を読みません。top-level の profile = "read-review" もサポートされなくなりました。移行方法は Advanced Config: Profiles で確認できます。

MCP は「読めた」と「動いた」を分ける

STDIO server は local process として起動します。

toml
[mcp_servers.docs]
command = "docs-server"
args = ["--read-only"]
env_vars = ["DOCS_TOKEN"]
startup_timeout_sec = 20
tool_timeout_sec = 60
enabled = true

streamable HTTP server では URL と credential の参照方法を分けます。

toml
[mcp_servers.tasks]
url = "https://mcp.example.internal/mcp"
bearer_token_env_var = "TASKS_MCP_TOKEN"
enabled = true

実 token を repo、記事、サポート用 screenshot に書かないでください。OpenAI の MCP documentation は STDIO、streamable HTTP、OAuth、environment header、timeout、tool allow/deny を個別に説明しています。

まず installed CLI が認識した定義を確認します。

bash
codex mcp list
codex mcp --help

OAuth 対応 server では codex mcp login <server-name> も使えます。ただし list に表示されることは、command の存在、URL への到達、認証成功、tool の正常動作までは証明しません。

復旧は一番手前の未確認ポイントから

最近の Codex CLI には --strict-config と doctor がありますが、古い version では利用できない場合があります。最初に local help を見ます。

bash
codex --version
codex --help
codex doctor --help

対応している場合は、次の read-only check が使えます。

bash
codex --strict-config doctor --summary

strict config は未認識 field を error にし、doctor は installation、config、auth、runtime の問題を調べます。成功しても provider request や MCP tool の成功を保証するものではありません。

症状ごとに入口を変えます。

Business/Enterprise の managed environment では、requirements.toml が approval、permission profile、web search、MCP allowlist、plugin、feature を制限できます。user の値が強制ルールに反すると、Codex は許可された値へ fallback して通知できます。詳細は Admin-enforced requirements にあります。別の local file に同じ値を書いても解決しません。

1回の変更には1つの観測可能な目的を持たせてください。所有レイヤーを選び、backup、最小編集、parse、低リスクな確認の順に進めます。失敗したら最初の未確認境界へ戻る方が、model、provider、permission、MCP をまとめて変更するより短時間で復旧できます。

設定ではなく coding agent の選択が目的なら、別の Claude Code と Codex の比較 が適切です。