# Codex 配置为什么不生效：.codex/ 目录结构的坑 > Author: Tony Lee > Published: 2026-04-01 > URL: https://tonylee.im/zh-CN/blog/codex-folder-structure-why-config-breaks/ > Reading time: 1 minutes > Language: zh-CN > Tags: codex, openai, ai-agents, developer-tools, configuration ## Canonical https://tonylee.im/zh-CN/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 - 一个仓库，两个目标 - 项目配置和用户配置撞名了 - trust level 才是真正的门槛 - 这种复杂性不是偶然的 ## Content Codex 的配置一直不生效。我改了 config.toml，在 AGENTS.md 里加了规则，文档也反复读了两遍。但没有任何变化，agent 还是把所有设置都忽略掉了。 最后我把整个目录结构拆开来看，才发现问题不在文件里写了什么，而在文件放在了哪里。 ## 一个仓库，两个目标 Codex 同时在解决两件事。一是对自身 beta 功能的快速迭代，二是跨 agent 的兼容性，也就是让 Claude Code、OpenCode 这类工具都能读懂的共享标准。 这两个目标产生了两个目录。 `.codex/` 是 Codex 专属的配置空间，沙盒策略、审批规则、运行时限制都放在这里。`.agents/` 是共享格式，技能、插件和 marketplace 注册表放在这一侧，遵循该标准的任何 agent 都可以读取。 一开始我不知道有这个区分，把 SKILL.md 放进了 `.codex/`，技能始终加载不了。把文件移到 `.agents/skills/` 之后立刻就好了。这个边界是严格的，如果其他 agent 也需要读，就放 `.agents/`，其余的才放 `.codex/`。 两个目录在 workspace-write 模式下都受只读保护，和 `.git/` 一样。 ## 项目配置和用户配置撞名了 项目根目录有一个 `.codex/`，家目录下也有一个 `~/.codex/`，但它们做的事完全不同。 项目里的 `.codex/` 存放团队共享的设置，比如沙盒策略、审批流程、agent 定义。`~/.codex/` 存放个人状态，比如 auth token、命令历史、worktree 管理文件。 我曾在 `~/.codex/agents/` 里做了一个 reviewer agent，然后不明白为什么队友看不到它。因为这个文件只存在于我自己的机器上。把文件移到项目的 `.codex/agents/reviewer.toml`，clone 仓库的时候就会跟着一起带过来。 Codex 还在 beta 阶段，这让情况更混乱。桌面应用的 worktree 文件、session 数据、auth 凭据全都堆进了 `~/.codex/`，没有清晰的隔离。"我的东西"和"项目的东西"之间的界限比应该有的要模糊得多。 配置优先级有固定顺序：managed config 优先于 session overrides，session overrides 优先于用户配置。如果某个设置没有生效，先确认你在改哪一层。 ## trust level 才是真正的门槛 这是大多数人卡住的地方，我也在这上面浪费了不少时间才搞明白。 Codex 不会从不受信任的仓库加载项目 `.codex/` 配置，完全不加载。你在一个刚 clone 下来的仓库里怎么编辑 config.toml 都没用。文件在那里，语法也对，但 Codex 会静默地忽略所有内容。 理解背后的原因之后就说得通了。`.agents/` 打开了外部技能流入你环境的通道，任何仓库都可能附带恶意配置。所以 Codex 做了这个权衡，更广的 agent 生态兼容性，换来对仓库配置更严格的信任验证。你必须显式地把一个项目标记为受信任，它的 `.codex/` 配置才会生效。 在用户配置里设置 `projects..trust_level = "trusted"`。网络访问默认也是关闭的，web 搜索有三种模式可选，cached、live 或 disabled。即使在 workspace-write 模式下，`.git/` 和 `.codex/` 也保持写保护。 我曾花了大约一个小时编辑一个项目的 config.toml，结果它被完全忽略了，原因就是没有设置 trust level。没有错误提示，没有任何警告，就是沉默。这大概是 Codex 配置里最常见的挫折，如果能有更好的错误提示，能帮很多人省下很多时间。 ## 这种复杂性不是偶然的 目录结构确实很乱，但不是随意堆出来的。Codex 在追求两个方向相反的目标。 快速 beta 迭代意味着 `.codex/` 要以超过文档更新速度的节奏积累配置文件、规则定义、hook 和应用管理产物。跨 agent 兼容性意味着 `.agents/` 需要一套独立的、可移植的技能和 marketplace 内容结构。而因为 `.agents/` 对外部代码打开了门，信任验证层就必须存在。 不确定文件该放哪里的时候，问自己一个问题，这是 Codex 专用的，还是其他 agent 也需要读？前者放 `.codex/`，后者放 `.agents/`。 配置不生效的时候，不要先去改文件内容。先确认文件在哪个目录，以及仓库是否已被信任。问题几乎总是出在这里。 ## Related URLs - Author: https://tonylee.im/zh-CN/author/ - Publication: https://tonylee.im/zh-CN/blog/about/ - Related article: https://tonylee.im/zh-CN/blog/eight-hooks-that-guarantee-ai-agent-reliability/ - Related article: https://tonylee.im/zh-CN/blog/claude-code-layers-over-tools-2026/ - Related article: https://tonylee.im/zh-CN/blog/codex-inside-claude-code-openai-plugin-strategy/ ## Citation - Author: Tony Lee - Site: tonylee.im - Canonical URL: https://tonylee.im/zh-CN/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/zh-CN/blog/ This content is original and authored by Tony Lee. Please attribute when quoting or referencing.