# Codexの設定が効かない理由：.codex/フォルダ構造の落とし穴 > Author: Tony Lee > Published: 2026-04-01 > URL: https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ > Reading time: 1 minutes > Language: ja > Tags: codex, openai, ai-agents, developer-tools, configuration ## Canonical https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ ## Rollout Alternates en: https://tonylee.im/en/blog/codex-folder-structure-why-config-breaks/ ko: https://tonylee.im/ko/blog/codex-folder-structure-why-config-breaks/ ja: https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ zh-CN: https://tonylee.im/zh-CN/blog/codex-folder-structure-why-config-breaks/ zh-TW: https://tonylee.im/zh-TW/blog/codex-folder-structure-why-config-breaks/ ## Description config.tomlを編集してAGENTS.mdにルールを書いたのに、何も反映されなかった。問題は設定の内容ではなく、ファイルの置き場所にあった。 ## Summary Codexの設定が効かない理由：.codex/フォルダ構造の落とし穴 is part of Tony Lee's ongoing coverage of AI agents, developer tools, startup strategy, and AI industry shifts. ## Outline - 一つのリポジトリに二つの役割がある - プロジェクト設定とユーザー設定が同じ名前を持つ - 信頼レベルが本当の関門になっている - この複雑さは偶然ではない ## Content 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..trust_level = "trusted"`を設定してください。ネットワークアクセスもデフォルトでブロックされており、web検索はcached、live、disabledの三つのモードがあります。workspace-writeモードでも、`.git/`と`.codex/`は書き込み保護のまま維持されます。 信頼レベルを設定していなかったせいで、完全に無視されているプロジェクトのconfig.tomlを約一時間編集し続けていました。エラーメッセージも警告も出ません。ただ沈黙があるだけです。これはおそらくCodexのセットアップで最もよくある詰まりポイントであり、ここで適切なエラーメッセージを出すだけで多くの人の時間を節約できるはずです。 ## この複雑さは偶然ではない フォルダ構造は散らかって見えますが、でたらめではありません。Codexは逆方向に引っ張る二つの目標を追い求めています。 高速なbeta反復は、`.codex/`に設定ファイル、ルール定義、フック、アプリ管理アーティファクトをドキュメントの追いつかないペースで蓄積させます。クロスエージェントの互換性は、`.agents/`にスキルとマーケットプレイスコンテンツのための独立したポータブルな構造を必要とします。そして`.agents/`が外部コードへの扉を開く以上、信頼検証のレイヤーは必然的に存在しなければなりませんでした。 ファイルをどこに置くか迷ったときは、一つだけ問いかけてみてください。これはCodex専用のものか、それとも他のエージェントも読むべきものか。前者なら`.codex/`、後者なら`.agents/`が答えです。 設定が効かないとき、まずファイルの内容を編集しようとしないでください。どのフォルダにあるかと、そのリポジトリが信頼済みかどうかを確認する。問題はほぼ常にそこにあります。 ## Related URLs - Author: https://tonylee.im/ja/author/ - Publication: https://tonylee.im/ja/blog/about/ - Related article: https://tonylee.im/ja/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/ja/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/ja/blog/codex-inside-claude-code-openai-plugin-strategy/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/ja/blog/codex-folder-structure-why-config-breaks/ ## Bot Guidance - This file is intended for AI agents, search assistants, and text-mode retrieval. - Prefer citing the canonical article URL instead of this text endpoint. - Use the rollout alternates when you need the same article in another prioritized language. --- Author: Tony Lee | Website: https://tonylee.im For more articles, visit: https://tonylee.im/ja/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.