Codex を使っていると、設定ファイルが2つ出てきます。
config.toml と AGENTS.md。名前も形式も違うので、どちらに何を書けばいいのか分からなくなります。
先に、いちばん分かりやすい整理を書きます。
config.toml には「どこまで動いてよいか」を書きます。 触れる範囲、確認するタイミング、使うモデル。境界の設定です。
AGENTS.md には「どう動いてほしいか」を書きます。 コードの書き方、守ってほしいルール、避けてほしいこと。振る舞いの指示です。
この2つを混ぜると、あとで分からなくなります。役割で分けて考えると、迷いません。
この記事で分かること
- 2つのファイルの役割分担
config.tomlの場所と、よく使う設定AGENTS.mdの階層と、書き方- 書きすぎないためのコツ
- 設定が効いていないときの確認
1. どちらも、必須ではありません
先に書いておきます。両方とも、なくても Codex は動きます。
初期設定のままでも使えます。毎回同じオプションを指定するのが面倒になってきたら、そのとき作れば十分です。
「設定ファイルを整えないと始められない」ということはありません。
2. config.toml
2-1. 場所
~/.codex/config.tomlホームフォルダの中の、.codex というフォルダです。先頭にピリオドが付いているので、通常は表示されません。
なければ、自分で作ります。
mkdir -p ~/.codex
touch ~/.codex/config.toml2-2. TOML という形式
見慣れない形式かもしれませんが、書き方は単純です。
# これはコメント
キー = "値"# から始まる行はコメントとして無視されます。設定の意図をメモとして残せるのが、この形式の良いところです。
文字列はクォートで囲みます。 ここを忘れるとエラーになります。
2-3. 最小の設定
まず、これだけ書いてみてください。
# 使うモデル
model = "gpt-5.1-codex"
# 触れる範囲：作業フォルダの中だけ書き込みを許可
sandbox_mode = "workspace-write"
# 確認するタイミング：範囲を超えるときだけ聞く
approval_policy = "on-request"これで、毎回オプションを指定しなくて済みます。
第2回で書いた --sandbox と --ask-for-approval を、毎回打たなくてよくなるということです。
なお、モデル名は変わります。 上の例をそのまま書くのではなく、手元で使えるものを確認してください。
/model2-4. よく使う設定
| 設定 | 何を決めるか |
|---|---|
model | 使うモデル |
sandbox_mode | 触れる範囲 |
approval_policy | 確認するタイミング |
model_reasoning_effort | どれくらい考えさせるか |
model_reasoning_effort は、クレジットの消費に直結します。
深く考えさせるほど、出力が増えてクレジットを使います。簡単な作業なら、低めにしておくと節約になります。
2-5. 用途別に切り替える
プロファイルという仕組みがあります。用途ごとに設定をまとめておいて、起動時に切り替えられます。
# 普段の設定
model = "gpt-5.1-codex"
sandbox_mode = "workspace-write"
approval_policy = "on-request"
# 調べもの用：読むだけ
[profiles.read]
sandbox_mode = "read-only"
# 慎重にやりたいとき
[profiles.careful]
approval_policy = "untrusted"使うときは、こう指定します。
codex --profile read注意点があります。 プロファイルは実験的な機能として提供されていた時期があります。手元で動くかどうかは、実際に試して確認してください。
2-6. 強い設定を、常用にしない
大事な注意です。
第2回で書いたとおり、制限をすべて外す設定があります。それを config.toml の全体設定に書かないでください。
一度書くと、すべてのプロジェクトで常に有効になります。そして、書いたこと自体を忘れます。
必要なときだけ、その場で指定する。 これが安全です。
3. AGENTS.md
3-1. 何を書くファイルか
「どう動いてほしいか」を、日本語で書くファイルです。
Codex は起動時にこれを読んで、振る舞いの基準として使います。
# このプロジェクトについて
- PHP 8.1 以上で動作します
- 関数は20行以内、ネストは3段まで
- 出力は表示の直前にエスケープしてください
- vendor/ と node_modules/ の中は編集しないでください3-2. 3つの階層があります
置き場所によって、効く範囲が変わります。
| 場所 | 効く範囲 |
|---|---|
~/.codex/AGENTS.md | すべてのプロジェクト |
| プロジェクトのルート | そのプロジェクト全体 |
| サブフォルダの中 | そのフォルダ以下 |
そして、これらは足し合わされます。 上の階層から順にたどって、すべて読み込まれます。
つまり、こういう使い分けができます。
自分の好みは、ホームに置く。「日本語で説明してほしい」「変更したファイルの一覧を最後に出してほしい」といった、プロジェクトを問わないもの。
プロジェクトの決まりごとは、ルートに置く。使っている言語のバージョン、コーディング規約、触ってほしくない場所。
特定の場所だけのルールは、そのフォルダに置く。
3-3. /init で下書きを作れます
ゼロから書くのが面倒なら、Codex に作らせられます。
/initプロジェクトの中身を解析して、AGENTS.md の下書きを作ってくれます。
そのまま使うのではなく、中身を読んで、要らないものを削るのがおすすめです。次の節で書きますが、長すぎると効かなくなります。
4. AGENTS.md の書き方
4-1. 判定できる形で書く
いちばん大事なコツです。
× 読みやすいコードを書いてください
○ 関数は20行以内、ネストは3段まで
× 適切にエラー処理をしてください
○ 失敗しうる箇所は必ず戻り値で返す。例外は投げない「読みやすい」の基準は、人によって違います。こちらの頭の中にしかない基準は、伝わりようがありません。
そして、判定できる形に書き直す作業は、自分の基準を決める作業でもあります。 決められないものは、相手にも決められません。
4-2. 禁止には、理由を添える
× この関数は使わないでください
○ この関数は使わないでください（外部入力が混ざると危険なため）理由があると、状況が変わったときに「これは当てはまるか」で判断してくれます。 理由がないと、例外扱いで破られます。
4-3. 触ってほしくない場所を書く
これは、実用的に効きます。
# 編集しないでください
- vendor/ と node_modules/（自動生成されるので、直しても消えます）
- build/ と dist/（ビルドの成果物です）
- 設定ファイルの本番用（.env.production）「自動生成されるので直しても消える」といった理由まで書いておくと、余計な作業をさせずに済みます。
4-4. テストの走らせ方を書く
見落としがちですが、これがあると作業が速くなります。
# テスト
- 実行コマンド: npm test
- テストファイルは tests/ の中に置く
- 新しい機能には、必ずテストを添えてください「テストを書いて」と頼んだときに、迷わなくなります。
5. 書きすぎないこと
ここが、実は難しいところです。
5-1. 長いほど、効かなくなります
あれもこれもと書き足すと、いちばん守ってほしい一行が、その他大勢に埋もれます。
Codex は、書いてあることを全部同じ重みで扱うわけではありません。長い文書の中では、個々の記述の存在感が薄まります。
5-2. 常駐させるものだけを書く
判断の目安を書きます。
プロジェクトの間、ずっと変わらないもの。 → AGENTS.md に書く。
そのときだけ必要な指示。 → 依頼文で渡す。
「今日はこのファイルだけ直して」といった一時的なことを書き込むと、あとで効かなくなったときに、原因が分からなくなります。
5-3. 定期的に削る
一度書いたら終わり、にしないでください。
使っているうちに、要らなくなった記述が溜まります。たまに読み返して、削ってください。
自分の感覚では、画面1〜2枚に収まる分量が、扱いやすい上限だと思います。
6. 方針を変えたときの扱い
長く使っていると、一度書いたルールを変えたくなります。
そのとき、古い記述をただ削除するだけだと、以前の方針が振る舞いに残ることがあります。 しばらくして、やめたはずのやり方が戻ってくる。
対策として、削除せずに「やめた」と書き残す方法があります。
# やめた方針
- 戻り値でエラーを返す方式 → やめました（例外に統一したため）。
今後は例外を投げてください。戻り値方式が出てきたら、それは古い指示です。見た目はきれいではありませんが、古いものが出てきたときに、否定する根拠が文書の側に残ります。
ただし、これも溜まりすぎると長くなります。しばらく出てこなくなったものは、消してかまいません。
7. 設定が効いていないとき
7-1. まず確認する
/statusいま実際に使われている設定が表示されます。書いたつもりが反映されていない、というのはよくあります。
7-2. よくある原因
ファイルの場所が違う。 ~/.codex/config.toml になっているか確認してください。
TOML の書式ミス。 クォートの閉じ忘れ、記号の間違い。1文字違うだけで、ファイル全体が読み込まれないことがあります。
起動オプションで上書きされている。 コマンドラインで指定したものが優先されます。
セッション中に変更した。 /permissions などで変えた設定は、その場では設定ファイルより優先されます。
7-3. 診断する
codex doctorインストールや設定の問題を、まとめて確認できます。
8. Claude Code を併用している方へ
次回への前置きとして、少しだけ書いておきます。
Claude Code を使っている方は、CLAUDE.md という似たファイルをご存知だと思います。
役割はよく似ていますが、別のファイルです。Codex は AGENTS.md、Claude Code は CLAUDE.md を読みます。
両方を使う場合、内容が食い違わないよう注意が必要です。 片方だけ更新して、もう片方が古いまま、ということが起こります。
次回は、この2つを併用する話を扱います。というより、片方に書かせて、もう片方にレビューさせるという使い方です。設定ファイルの共有をどうするかも、そこで書きます。
まとめ
- 設定ファイルは2つ。どちらも必須ではない
config.toml=「どこまで動いてよいか」。 触れる範囲、確認のタイミング、モデルAGENTS.md=「どう動いてほしいか」。 書き方のルール、禁止事項config.tomlは~/.codex/に置く。TOML はコメントを残せるのが利点AGENTS.mdは3階層（ホーム／プロジェクトルート／サブフォルダ）で、足し合わされる- 自分の好みはホーム、プロジェクトの決まりはルート、と分けると整理しやすい
- 判定できる形で書く。 「読みやすく」ではなく「20行以内」
- 禁止には理由を添える
- 長くしすぎない。 埋もれると効かなくなる
- 強い設定を全体設定に書かない。 必要なときだけ指定する
- 効いていないときは
/statusで確認。TOML の書式ミスが多い
設定は、最初から完璧に作らなくて大丈夫です。使っていて「毎回同じことを言っているな」と気づいたら、そのとき1行足す。その繰り返しで育っていきます。
次回はシリーズ最終回です。Claude Code と組み合わせる使い方を扱います。どちらか一方を選ぶのではなく、片方に書かせて、もう片方にレビューさせるという運用の話です。
※本記事の情報は2026年8月時点のものです。設定項目は変更されることがあるため、最新の情報は公式ドキュメントをご確認ください。
