.codexとは？

Posted at 2026-05-02

エグゼクティブサマリー

.codex は、OpenAI CodexCLIの設定を置くためのフォルダです。

自分の全プロジェクトで使う標準設定はグローバルの .codex、リポジトリごとの差分はプロジェクトルート側の .codex に置く、と考えると整理しやすいです。

一言でいうと、グローバルは「自分の標準設定」、プロジェクトルートは「その案件だけの上書き」です。

置き場所	役割	例
グローバル `.codex`	自分の全プロジェクト共通設定	`<HOME>/.codex/config.toml`
プロジェクトルート `.codex`	そのリポジトリ専用の設定上書き	`<repo>/.codex/config.toml`

公式ドキュメントでも、ユーザー設定は ~/.codex/config.toml、プロジェクト単位の上書きはリポジトリ内の .codex/config.toml に置けます。

.codex は設定用フォルダです。

たとえば、モデル、承認ポリシー、sandbox、MCP、hooks、rules などは .codex/config.toml に寄せる領域です。

一方で、「このリポジトリではこのテストを実行する」「この書き方を守る」「PR前にこれを確認する」のような自然言語の開発ルールは、主に AGENTS.md に書くと見通しがよくなります。

ここを混ぜると、あとから「設定の話なのか、Codexへの指示文の話なのか」が少し分かりにくくなります。

config.toml は、次の順で強くなります。

プロジェクト内の .codex/config.toml は、プロジェクトルートからカレントディレクトリまで順に見られます。よりカレントディレクトリに近い設定ほど優先されます。

つまり、普段の標準設定はグローバル側に置き、案件・リポジトリごとの差分だけをプロジェクト側に置くのが自然です。

注意点として、プロジェクト側の .codex は、Codexがそのプロジェクトを trusted と判断した場合だけ読み込まれます。untrusted の場合、プロジェクトローカルの config、hooks、rules などはスキップされます。

Codexへの自然言語の指示文は、主に AGENTS.md で管理します。

読み込み順は次のイメージです。

グローバル
- <Codex home>/AGENTS.override.md
- なければ <Codex home>/AGENTS.md
プロジェクトルート
- <repo>/AGENTS.override.md
- なければ <repo>/AGENTS.md
カレントディレクトリに近い階層
- 例: <repo>/<subdir>/AGENTS.override.md
- なければ <repo>/<subdir>/AGENTS.md

AGENTS.override.md がある場合は、同じ階層の AGENTS.md より優先されます。

また、Codexは global → repo root → deeper directory の順で指示を結合します。後から読み込まれる、つまりカレントディレクトリに近い指示ほど優先されやすい、という理解でよさそうです。

<HOME>/.codex は、自分の全体ルールや共通設定を置く場所です。

たとえば、デフォルトモデル、承認ポリシー、MCP、共通 hooks / rules などを置きます。

<repo>/.codex は、そのプロジェクト専用設定を置く場所です。

たとえば、このリポジトリだけ sandbox 設定を変える、専用 hooks / rules を置く、といった使い方です。

<repo>/AGENTS.md は、そのプロジェクトでCodexに守らせたい開発ルールを置く場所です。

たとえば、テストコマンド、コーディング規約、PR前チェック、レビュー観点などを書きます。

.codex は設定、AGENTS.md は指示文。

グローバル .codex は自分の標準設定、プロジェクトルート .codex はその案件だけの上書き。

この2つを分けておくと、Codexまわりの設定がだいぶ見通しよくなります。