【Codex】⑤⑥　Codex設定ファイル：AGENTS.mdとconfig.tomlは何者か？役割と違いを徹底解説

Codex CLI
2026.07.19
  • AGENTS.md : Claude.md , .github/copilot-instructions.md のようなSDD指示書
  • .codex/config.toml : Codexの動作設定（LLM model , approval policy , sandbox_mode, reasoning effort(High-Low),,Etc.）

はじめに

Codexを使って本格的なソフトウェア開発を進める際、重要になるのが次の2つの設定ファイルです。

  • AGENTS.md
  • config.toml

AGENTS.mdについては、Claude CodeのCLAUDE.mdや、GitHub Copilotの.github/copilot-instructions.mdに近いものだと理解している人も多いでしょう。

一方、config.tomlについては、

  • 何を設定するファイルなのか
  • AGENTS.mdと何が違うのか
  • Codex CLIとVS CodeのCodex拡張で共通して使えるのか
  • どこに配置すればよいのか

といった点が、少し分かりにくいかもしれません。

本記事では、Codexを使った開発を進めるうえで重要となるAGENTS.mdとconfig.tomlについて、両者の役割と違いを整理します。

結論：AGENTS.mdとconfig.tomlの違い

まず結論から言うと、次のように整理できます。

ファイル一言でいうと主に指定するもの
AGENTS.mdCodexへの業務指示書何を、どのルールで開発するか
config.tomlCodex本体の動作設定ファイルどのモデル・権限・環境・ツールで動くか

つまり、

AGENTS.md＝仕事の進め方
config.toml＝仕事をする道具や権限の設定

です。

この2つは似ているように見えますが、担当する役割が異なります。

AGENTS.mdは、Codexに対してプロジェクト固有の開発方針やルールを伝えるためのファイルです。

一方のconfig.tomlは、Codexそのものをどのような設定で動かすかを指定するファイルです。

1. AGENTS.mdは何者か

ユーザーの理解どおり、次のファイルとほぼ同じ仲間です。

  • Claude Code：CLAUDE.md
  • GitHub Copilot：.github/copilot-instructions.md
  • Codex：AGENTS.md

ファイル名は正確には、通常すべて大文字で AGENTS.md、CLAUDE.md です。

また、GitHub Copilot側は .github/copilot-instructions.md です。

参考：

例えば、AGENTS.mdには次のようなことを書きます。

# AGENTS.md

## プロジェクト概要
このアプリはPythonとFastAPIで構築する。

## 開発ルール
- Python 3.12を使用する
- 関数には型ヒントを付ける
- 既存コードを調査してから修正する
- 不要なライブラリを追加しない
- 修正後は必ずテストを実行する

## 禁止事項
- .envをGitに登録しない
- mainブランチを直接変更しない
- ユーザーの確認なしに既存DBを削除しない

## 完了条件
- pytestがすべて成功する
- READMEを更新する
- 変更内容を最後に報告する

この例では、Codexに対して次の情報を伝えています。

  • このプロジェクトが何を作るものなのか
  • どのプログラミング言語やフレームワークを使うのか
  • コードをどのような方針で変更するのか
  • 何をしてはいけないのか
  • どの状態になれば作業完了とみなすのか

Codexは作業開始前にAGENTS.mdを読み、そこに書かれた内容をプロンプトの一部として取り込みます。

ルートディレクトリだけでなく、下位フォルダにも配置でき、現在の作業場所に近いファイルほど優先される階層構造を持っています。

参考：

AGENTS.mdは「司令塔」なのか

AGENTS.mdを「Codexの司令塔」と表現すると、直感的には分かりやすいでしょう。

ただし、厳密には、AGENTS.mdを「司令塔」と呼ぶのは少しだけ強すぎます。

正確には、Codexに渡す「常設の業務指示書・プロジェクト取扱説明書」です。

「司令塔」ではなく「就業規則」

厳密には、AGENTS.md自身が処理を実行したり、別のエージェントに仕事を振ったりするわけではありません。

実際の司令塔は、モデル、ツール、ユーザー、実行結果をつなぐCodexのエージェントループ／ハーネスです。

AGENTS.mdは、その司令塔が参照する「業務マニュアル」に当たります。

参考：

したがって、技術ブログでは次の表現が正確です。

AGENTS.mdはCodexの司令塔そのものではなく、Codexが継続的に参照するプロジェクト固有の指示書である。

会社にたとえるなら、Codex本体が実際に判断して作業を進める社員や担当者であり、AGENTS.mdは、その社員に渡される就業規則、業務マニュアル、設計標準、開発ルールに相当します。

2. config.tomlは何者か

config.tomlは、Codexアプリ、Codex CLI、Codex IDE拡張そのものの動作を設定するファイルです。

たとえるなら、

  • AGENTS.md：社員に渡す作業指示書
  • config.toml：社員が使うPC、入室権限、使用工具、安全装置の設定

です。

AGENTS.mdが、自然言語で開発ルールや方針を書くファイルであるのに対し、config.tomlはCodexのシステム設定を記述するファイルです。

TOMLとは何か

config.tomlの.tomlは、設定ファイルの記述形式を表しています。

TOMLは、設定内容を比較的読みやすい形で記述できるフォーマットです。

例えば、次のように、設定名と値を=で結んで記述します。

model = "使用するモデル名"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

JSONやYAMLと同じように、アプリケーションの設定情報を保存するために使われます。

config.tomlで設定する内容

config.tomlでは、例えば次のような項目を設定します。

# 使用するモデル
model = "使用するモデル名"

# コマンド実行前に確認を求めるか
approval_policy = "on-request"

# ファイル変更をどこまで許可するか
sandbox_mode = "workspace-write"

# 推論の強さ
model_reasoning_effort = "high"

ほかにも、次のような設定を扱います。

  • 使用モデル
  • 推論レベル
  • コマンド実行時の確認方法
  • ファイルの読み書き権限
  • ネットワークアクセス
  • Web検索
  • MCPサーバー
  • 使用可能なツール
  • 通知
  • プロファイル切り替え
  • 実験機能の有効化

例えばapproval_policyは、Codexがコマンド実行前にどのタイミングで確認するかを指定します。

sandbox_modeは、読み取り専用、ワークスペース内書き込み許可、広範囲のアクセス許可など、実行時の権限を決めます。

参考：

approval_policyとは

Codex CLIは、コードを読むだけでなく、設定によっては次のような操作を実行します。

  • ファイルの作成
  • ソースコードの変更
  • テストコマンドの実行
  • Gitコマンドの実行
  • パッケージのインストール
  • 外部ネットワークへのアクセス

これらを毎回無条件に許可すると、意図しない変更が発生する可能性があります。

そこで、approval_policyを使用して、どのような操作の前にユーザーへ確認するかを設定します。

例えば、次の設定です。

approval_policy = "on-request"

これは、必要な場面でCodexがユーザーに実行許可を求める設定です。

つまり、Codexにどの程度自動で作業を任せるかを決める、安全性に関わる設定です。

sandbox_modeとは

sandbox_modeは、Codexがアクセスできる範囲を制限する設定です。

例えば、次の設定があります。

sandbox_mode = "workspace-write"

この設定では、Codexが作業中のワークスペース内にファイルを書き込めるようにします。

一方、より制限の強い設定では、ファイルを読むだけにして、書き込みを禁止することもできます。

逆に、非常に広い権限を与えれば、ワークスペース外のファイルやシステムにアクセスできる場合もあります。

したがって、sandbox_modeは、Codexにどこまで操作を許可するかを決める設定だと理解するとよいでしょう。

モデルと推論レベルの設定

config.tomlでは、Codexが使用するモデルや、推論にどの程度の計算を使うかも設定できます。

例：

model = "使用するモデル名"
model_reasoning_effort = "high"

model_reasoning_effortを高くすると、複雑なコード解析や設計判断に向いた動作が期待できます。

ただし、処理時間や利用量が増える可能性もあるため、作業内容に応じて調整します。

単純なコード修正では低めにし、大規模な設計変更や複雑なバグ解析では高めにする、といった使い分けが考えられます。

3. config.tomlはどこにあるか

個人全体に適用する基本設定は、通常ここです。

~/.codex/config.toml

LinuxやmacOSでは、ホームディレクトリ配下の.codexフォルダに配置されます。

Windowsでは、一般的に次のような場所になります。

C:\Users\ユーザー名\.codex\config.toml

例えば、Windowsのユーザー名がonoであれば、次のようになります。

C:\Users\ono\.codex\config.toml

プロジェクト固有の設定

プロジェクト固有の設定は、リポジトリ内に置けます。

プロジェクトルート/
├─ AGENTS.md
├─ .codex/
│  └─ config.toml
├─ src/
└─ tests/

この構成では、役割が次のように分かれます。

AGENTS.md
└─ プロジェクトの開発方針、禁止事項、テスト方法、完了条件

.codex/config.toml
└─ Codexのモデル、権限、承認方法、ツール、実行環境

Codex CLIとCodex IDE拡張は、基本的に同じ設定階層を共有します。

個人設定に加え、信頼済みプロジェクトでは.codex/config.tomlによるプロジェクト固有の上書きも可能です。

参考：

4. 2つの違いを具体例で比較する

たとえば、「FastAPIアプリを開発する」という場合です。

AGENTS.mdに書くこと

- FastAPIを使用する
- APIはREST形式にする
- テストにはpytestを使用する
- 既存APIとの互換性を維持する
- 修正後にpytestを実行する

これは、開発内容と作業方法の指示です。

Codexに対して、どの技術を使い、どのルールを守り、何を完了条件とするかを伝えています。

config.tomlに書くこと

approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "high"

これは、Codexをどの権限・動作モードで働かせるかの設定です。

config.tomlにはMCPサーバーの起動コマンド、URL、使用可能なツール、承認方法なども登録できます。

つまり、外部ツールとの接続設定も担当します。

参考：

5. 最も分かりやすい比喩

会社に置き換えると、次の関係です。

ユーザーの依頼
    ↓
Codex本体
    ├─ AGENTS.mdを読む
    │    └─ 開発方針・禁止事項・完了条件
    │
    ├─ config.tomlを読む
    │    └─ モデル・権限・ツール・実行環境
    │
    └─ コード調査・修正・テストを実行

もう少し具体的に会社組織へ置き換えると、次のようになります。

Codexの構成要素会社での例
ユーザーのプロンプト上司からの今回の仕事の依頼
Codex本体実際に作業する担当者
AGENTS.md就業規則、設計標準、業務マニュアル
config.tomlPC設定、使用工具、アクセス権限、安全装置
ソースコード作業対象となる製品や設計書
テスト品質検査、動作確認
Git変更履歴と承認記録

したがって、ブログの導入ではこう書くと分かりやすいです。

AGENTS.mdは「Codexにどのように仕事をさせるか」を自然言語で記述する指示書である。一方、config.tomlは「Codexをどのモデル、権限、ツール、実行環境で動かすか」を指定するシステム設定ファイルである。前者が業務ルール、後者が動作環境の設定に相当する。

6. AGENTS.mdとconfig.tomlは両方必要なのか

必ず両方を作成しなければCodexが動かない、というわけではありません。

どちらのファイルがなくても、Codex CLIやCodex拡張を利用できる場合があります。

しかし、継続的にプロジェクトを開発する場合は、両方を適切に設定することで、Codexの作業品質と安全性を高められます。

AGENTS.mdがない場合

AGENTS.mdがない場合、Codexは毎回のプロンプトとソースコードから、開発ルールを推測することになります。

その結果、次のような問題が起こる可能性があります。

  • 毎回同じ指示を入力する必要がある
  • 使用するライブラリや書き方が統一されない
  • テストを実行せずに作業を終了する
  • 変更してはいけないファイルを変更する
  • プロジェクト固有の事情を理解できない
  • セッションごとに回答や実装方針が変わる

config.tomlがない場合

config.tomlがない場合、Codexは標準設定やコマンドラインオプションに基づいて動作します。

ただし、自分が希望するモデル、承認方法、サンドボックス権限、MCP接続などが毎回同じになるとは限りません。

そのため、次のような設定を固定したい場合は、config.tomlが有効です。

  • 毎回同じモデルを使いたい
  • 推論レベルを固定したい
  • ファイル書き込みをワークスペース内だけに制限したい
  • コマンド実行前に確認を求めたい
  • 特定のMCPサーバーを利用したい
  • チームやプロジェクトでCodexの動作条件を統一したい

7. プロンプトとの違い

AGENTS.mdと通常のプロンプトの違いも重要です。

通常のプロンプトは、今回の作業内容を指示するものです。

例えば、次のような依頼です。

calculator.pyに掛け算機能を追加してください。
既存テストを確認し、必要なテストケースも追加してください。

一方、AGENTS.mdには、毎回の作業で共通して守らせたいルールを書きます。

- 修正前に既存コードを調査する
- 既存仕様との互換性を維持する
- 修正後は必ずpytestを実行する
- テスト失敗時には作業完了としない

つまり、次の違いがあります。

種類内容
ユーザーのプロンプト今回実施してほしい具体的な作業
AGENTS.mdすべての作業に共通するプロジェクトルール
config.tomlCodexが作業する際のシステム設定

8. GitHubに登録するべきものと、登録しないもの

一般的には、プロジェクト固有のAGENTS.mdはGitHubに登録することができます。

チーム全員が同じ開発ルールを共有できるためです。

例えば、次のような構成です。

project/
├─ .git/
├─ .github/
│  └─ copilot-instructions.md
├─ .codex/
│  └─ config.toml
├─ AGENTS.md
├─ CLAUDE.md
├─ README.md
├─ src/
└─ tests/

ただし、config.tomlには個人情報や認証情報を直接書かないように注意が必要です。

特に、次のような情報をGitHubへ登録してはいけません。

  • APIキー
  • アクセストークン
  • パスワード
  • 秘密鍵
  • 社内サーバーの認証情報
  • 個人専用の機密URL

これらは環境変数や、Git管理対象外のファイルで管理する必要があります。

例えば、.gitignoreに次のような設定を追加します。

.env
.env.*
*.key
*.pem

9. 複数のAIコーディングエージェントを使う場合

Codex、Claude Code、GitHub Copilotを同じプロジェクトで使う場合、次のようなファイルが共存することがあります。

project/
├─ AGENTS.md
├─ CLAUDE.md
├─ .github/
│  └─ copilot-instructions.md
├─ .codex/
│  └─ config.toml
└─ README.md

それぞれの役割は次のとおりです。

AIツール主な指示ファイル
OpenAI CodexAGENTS.md
Claude CodeCLAUDE.md
GitHub Copilot.github/copilot-instructions.md

内容が大きく異なると、AIツールごとに別の実装方針が提示される可能性があります。

そのため、プロジェクトの基本方針は共通化し、それぞれのファイルに同じ基本ルールを書く方法が考えられます。

ただし、各ツール固有の機能や読み込み方法があるため、ファイルを単純にコピーするだけではなく、それぞれのツールに適した形に調整する必要があります。

10. 実際の使い分け

Codexに何かを設定したい場合は、次のように考えると判断しやすくなります。

開発ルールに関する内容

次の内容はAGENTS.mdに書きます。

  • 使用言語
  • 使用フレームワーク
  • コーディング規約
  • フォルダ構成
  • テスト方法
  • 実行コマンド
  • 禁止事項
  • セキュリティ上の注意
  • Git運用ルール
  • 作業完了条件
  • 変更後の報告形式

Codexの動作に関する内容

次の内容はconfig.tomlに書きます。

  • 使用モデル
  • 推論レベル
  • 承認ポリシー
  • サンドボックスモード
  • ネットワークアクセス
  • Web検索
  • MCPサーバー
  • 使用可能ツール
  • 通知設定
  • プロファイル
  • 実験機能

まとめ

AGENTS.mdとconfig.tomlは、どちらもCodexを自分の開発環境に合わせて調整するための重要なファイルです。

ただし、両者の役割は明確に異なります。

ファイル役割
AGENTS.mdCodexに守らせるプロジェクト固有の業務ルール
config.tomlCodex本体のモデル、権限、ツール、実行方法の設定

最も簡単に表現すると、次のようになります。

AGENTS.mdは、Codexにどのように仕事をさせるかを書くファイルである。

config.tomlは、そのCodexをどのような装備、権限、環境で動かすかを書くファイルである。

AGENTS.mdはCodexの司令塔そのものではなく、Codexが継続的に参照するプロジェクト固有の指示書です。

そしてconfig.tomlは、Codexがその指示に従って作業する際の、モデル、実行権限、サンドボックス、ツールなどを設定するファイルです。

この整理を土台にすれば、⑤をAGENTS.md実践編、⑥をconfig.tomlによるCodex動作環境のカスタマイズ編として構成できます。

次の記事

次回以降は、次の内容を実践形式で解説します。

⑤ AGENTS.md実践編

  • AGENTS.mdの作成方法
  • Codex CLIがAGENTS.mdを読み込んでいるか確認する方法
  • プロジェクトルートとサブフォルダでの優先順位
  • Pythonプロジェクト用の実用的なテンプレート
  • Codex App、Codex CLI、VS Code拡張での違い
  • 指示が守られない場合の原因と対策

⑥ config.toml実践編

  • config.tomlの作成場所
  • 使用モデルの指定
  • 推論レベルの変更
  • approval_policyの設定
  • sandbox_modeの設定
  • Web検索とネットワークアクセス
  • MCPサーバーの登録
  • 個人設定とプロジェクト設定の使い分け
  • 安全性と自動化のバランス

コメント

タイトルとURLをコピーしました