Codexの設定が効かない理由：.codex/フォルダ構造の落とし穴

Codexの設定がまったく反映されない状況に陥りました。config.tomlを編集して、AGENTS.mdにルールを追記して、ドキュメントを二度読み直した。それでも何も変わらない。エージェントはすべてを無視し続けました。

最終的にフォルダ構造全体を丁寧に調べ直しました。問題はファイルの中身ではありませんでした。ファイルがどこに置かれているか、それだけが原因でした。

一つのリポジトリに二つの役割がある

Codexは同時に二つの課題を解決しようとしています。一つはbeta機能の高速な試行錯誤、もう一つはClaude CodeやOpenCodeといった他のツールとも共有できるクロスエージェントの互換性です。

この二つの方向性が、二つのフォルダを生み出しています。

.codex/はCodex専用の設定スペースです。サンドボックスポリシー、承認ルール、ランタイムのガードレールはここに置きます。.agents/は共有フォーマット側です。スキル、プラグイン、マーケットプレイスのレジストリはこちらに置き、標準に対応するエージェントであれば誰でも読み取れます。

最初はこの分離を知りませんでした。SKILL.mdを.codex/の中に入れたところ、スキルが一切ロードされませんでした。.agents/skills/に移動したら即座に動きました。境界は厳格です。他のエージェントが読む必要があるものは.agents/に置く。それ以外はすべて.codex/に入れる。

どちらのフォルダも、.git/と同様にworkspace-writeモードで書き込み保護がかかります。

プロジェクト設定とユーザー設定が同じ名前を持つ

プロジェクトルートに.codex/があり、ホームディレクトリに~/.codex/があります。この二つはまったく別の役割を担っています。

プロジェクトの.codex/はチームと共有する設定を持ちます。サンドボックスポリシー、承認ワークフロー、エージェント定義などです。~/.codex/は個人の状態を持ちます。認証トークン、コマンド履歴、worktree管理ファイルがここに入ります。

~/.codex/agents/にレビュワーエージェントを作ったとき、なぜチームメンバーにそれが届かないのか理解できませんでした。自分のマシンにしか存在しなかったからです。ファイルをプロジェクトの.codex/agents/reviewer.tomlに移動してはじめて、リポジトリと一緒にcloneされるようになりました。

Codexがまだbeta段階であることも混乱に拍車をかけます。デスクトップアプリのworktreeファイル、セッションデータ、認証情報がすべて~/.codex/に積み重なり、「自分のもの」と「プロジェクトのもの」の境界線が曖昧になっています。

設定の優先順位は決まった順序に従います。managed configが最優先で、次にセッションオーバーライド、その次にユーザー設定という順番です。何かが反映されないとき、どのレベルを編集しているかをまず確認してください。

信頼レベルが本当の関門になっている

ほとんどの人がここで詰まります。自分も理由がわかるまでかなりの時間を費やしました。

Codexは信頼されていないリポジトリからプロジェクトの.codex/を読み込みません。まったくです。新しくcloneしたリポジトリでconfig.tomlをどれだけ編集しても、何も適用されません。ファイルは存在して、構文も正しい。それでもCodexはすべてを黙って無視します。

理由はわかると納得できます。.agents/は外部スキルを自分の環境に流し込む経路を開きます。悪意のある設定を仕込んだリポジトリが存在し得ます。そのためCodexはこのトレードオフを選びました。エージェントエコシステムとの広い互換性を持ちつつ、リポジトリが提供する設定には厳格な信頼検証を要求する。プロジェクトの.codex/設定を有効化するには、そのプロジェクトを明示的に信頼済みとしてマークする必要があります。

ユーザー設定でprojects.<path>.trust_level = "trusted"を設定してください。ネットワークアクセスもデフォルトでブロックされており、web検索はcached、live、disabledの三つのモードがあります。workspace-writeモードでも、.git/と.codex/は書き込み保護のまま維持されます。

信頼レベルを設定していなかったせいで、完全に無視されているプロジェクトのconfig.tomlを約一時間編集し続けていました。エラーメッセージも警告も出ません。ただ沈黙があるだけです。これはおそらくCodexのセットアップで最もよくある詰まりポイントであり、ここで適切なエラーメッセージを出すだけで多くの人の時間を節約できるはずです。

この複雑さは偶然ではない

フォルダ構造は散らかって見えますが、でたらめではありません。Codexは逆方向に引っ張る二つの目標を追い求めています。

高速なbeta反復は、.codex/に設定ファイル、ルール定義、フック、アプリ管理アーティファクトをドキュメントの追いつかないペースで蓄積させます。クロスエージェントの互換性は、.agents/にスキルとマーケットプレイスコンテンツのための独立したポータブルな構造を必要とします。そして.agents/が外部コードへの扉を開く以上、信頼検証のレイヤーは必然的に存在しなければなりませんでした。

ファイルをどこに置くか迷ったときは、一つだけ問いかけてみてください。これはCodex専用のものか、それとも他のエージェントも読むべきものか。前者なら.codex/、後者なら.agents/が答えです。

設定が効かないとき、まずファイルの内容を編集しようとしないでください。どのフォルダにあるかと、そのリポジトリが信頼済みかどうかを確認する。問題はほぼ常にそこにあります。