Codexを使うなら、config.tomlとAGENTS.mdを押さえておきたい

記事の概要

OpenAI Codex CLIの設定まわりを体系的に整理した記事。config.tomlは「実行環境（モデルや推論の強さなど実行時の条件）」を、AGENTS.mdは「仕事の進め方（検証方法や作業上の制約）」を決めるという役割分担を軸に、設定の読み込み優先順位・AGENTS.mdの探索範囲・プロファイルの新しい書き方・効かないときの切り分け方まで解説しています。Claude Code（settings.json／CLAUDE.md）との対比もあり、併用者に特に参考になります。

執筆背景

• 著者は以前から「Claude Code の settings.json / CLAUDE.md は設定した方がいい」というシリーズ記事を書いている。Codexにも似た役割のファイルがあるが、読み込まれ方はツールごとに異なるため確かめる必要がある、という視点。
• ファイルを置くだけで意図どおりに効くわけではなく、設定の優先順位・起動場所・読み込まれる指示を確認して初めて同じ条件でCodexを使える。

実行設定と仕事の指示を分ける

「レビューだけ頼みたい」という依頼ひとつでも、「変更の根拠を先に示す」のは文章の指示、「ファイルを書き換えられない環境で実行する」のは権限の設定、と効く場所が違う。

• 公式ベストプラクティスも「設定の置き場所を用途で分ける」ことを案内：個人用の既定値は ~/.codex/config.toml、リポジトリ固有の動作は .codex/config.toml、CLIの上書きは単発の作業用。
• AGENTS.mdに「勝手に変更しない」と書いてもサンドボックスの書き込み権限は消えない。逆に読み取り専用起動だけではレビュー観点は伝わらない。「指示の問題」と「実行権限の問題」は別。
• 初めて使うときは承認とサンドボックスを厳しい既定値のままにし、必要性が分かってから信頼できるリポジトリや決まった作業だけ権限を広げる。

config.toml の優先順位（高い順）

1. CLIのフラグと --config による指定
2. プロジェクトの .codex/config.toml（作業ディレクトリに近い方を優先）
3. --profile で選んだ設定ファイル
4. 個人の ~/.codex/config.toml
5. 組織が用意したクラウド管理の既定値（配信されている場合）
6. システムの設定
7. 組み込みの既定値

設定例：差分の小さい設定から始める

# ~/.codex/config.toml（例：Web検索の方式だけ明示）
web_search = "cached"

• cached（検索用キャッシュ利用）／ live（最新情報が必要な調査）／ disabled（検索を使わない）。
• 一度だけ変えたいならファイルを書き換えず codex -c 'web_search="live" のように起動時指定できる。値はTOMLとして解釈されるため、引用の仕方にも注意。
• エラー表示の有無だけでなく、意図した型と値で読まれたかまで確かめる。

設定プロファイルは「別ファイル」に書く（仕様変更に注意）

• 用途別に変えたい項目（例：レビュー時だけ推論を強める）は、~/.codex/review.config.toml のような別ファイルに差分だけ書き、codex --profile review で起動。

# ~/.codex/review.config.toml
model_reasoning_effort = "high"
web_search = "disabled"

• プロファイルは基本設定を「置き換える」ファイルではなく上に重ねるもの。省略した項目は他の階層から来る。プロジェクト設定とCLI指定の方が優先される点も残る。
• 「設定プロファイル」と、ファイルや通信先をまとめる「権限プロファイル」は別の機能。どちらもprofileと呼ばれるため、エラー調査時はどちらの名前かまで確認する。

AGENTS.md は「起動場所までの指示」を重ねる

• 個人の共通指示は ~/.codex/AGENTS.md、チームの指示はリポジトリ側。
• まだなければCLIの /init で初期版を作成できる（生成内容は出発点として、実際のビルド・テスト・レビュー・公開の手順へ書き換える）。
• 探索はプロジェクトのルートから現在の作業ディレクトリまでをたどる。例：codex --cd backend で起動すればルート＋backendの指示を組み合わせられる。ルートで起動しただけで全サブディレクトリのAGENTS.mdを読む仕組みではない。
• 各ディレクトリでは AGENTS.override.md → AGENTS.md → 設定した代替名の順に探し、その階層で読むのは最大1ファイル。override は同階層のAGENTS.mdへ「追記」するファイルではない（誤解しやすい点）。
• 公式ベストプラクティスが挙げる記載項目：リポジトリの構成、実行方法、ビルド・テスト・lint、開発規約、制約、完了の定義と検証方法。

Claude Codeでも読み込む方式を選べる

• Claude Code公式の agents-md mod は複数モードを持つ：
  • claude-md-or-agents-md（既定）— プロジェクト固有の CLAUDE.md がないときに AGENTS.md を読む
  • claude-md-and-agents-md — 両方を読む
  • claude-md — 従来どおりCLAUDE.mdだけ
  • managed-only — 管理された指示だけ
• 設定は /config の「Project instructions」またはユーザー設定の pluginConfigs に指定。プロジェクトの .claude/settings.json ではなく ~/.claude/settings.json・--settings・管理設定のいずれかに置く点に注意。

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

共通の指示を、すべて同じ場所へ移さない

• リポジトリ固有のコマンドを共通ファイルへ書くと、別プロジェクトで存在しないコマンドを実行する原因になる。
• 両ツールで読む設定にしても同じ指示を重複させるのではなく、ツール固有の操作はCLAUDE.md・Codex設定へ、両方で守る判断だけAGENTS.mdへ。

AGENTS.md の書き方：迷ったときの判断から考える

# このリポジトリでの作業
- 変更前に、対象ディレクトリの説明と既存の検証手順を読む。
- 既存の作業中の差分を確認し、今回の修正と混ぜない。
- 動作を変える場合は、変更前の問題と変更後の確認方法を示す。
- 実行した検証、その結果、未実施の範囲を報告する。
- commit、push、公開は依頼された場合に行う。

• 「丁寧に」「十分に」「よく考えて」を増やしても迷う場所は明らかにならない。再現条件となるテスト名など、具体的な手がかりを書く。
• コードを読めば分かる関数一覧の写経は不要（実装変更のたびに更新が必要になる）。残すべきは「調べるだけでは決まらない判断」「毎回伝えている確認方法」。
• 短く正確なファイルから始め、同じミスを2回したときだけルールを追加する。
• 指示の結合量には既定で32KiBの上限。日本語は文字数とバイト数が一致しない。上限に近づいたら、値を増やす前に「毎回必要な指示」と「特定の仕事だけの手順」を分ける。

効いていないときは、文章を強化する前に「調べる」

• 設定を直したら新しいセッションで /status で現在の設定を確認。
• 想定と違えば /debug-config で読み込み元の階層と有効状態、適用される管理方針を調査できる（診断表示の階層は優先順位の低い方から並ぶため注意）。
• AGENTS.mdは「読み込んだ指示ファイルを示して」と自己申告させるだけではなく、読み取りだけの小さな依頼で実際に検証が実行されたかまで見る。「読まれていない問題」と「読んでも曖昧で実行できない問題」は直し方が違う。

この記事から得られる学び

• エージェントCLIの設定は「実行環境（config）」と「指示（AGENTS.md/CLAUDE.md）」と「権限（サンドボックス）」の3層に分けて考えると切り分けやすい。
• 設定は階層と優先順位（ nearer-wins ）で決まり、起動ディレクトリ自体が設定の一部。
• プロファイル周りはバージョンで仕様が変わっている（0.134.0以降は別ファイル方式）ので、古い記事を鵜呑みにしない。
• 指示が効かないときは「より強い言葉」を足す前に、そのファイルが読み込まれているかを検証する。