Codex 配置为什么不生效：.codex/ 目录结构的坑

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.<path>.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/。

配置不生效的时候，不要先去改文件内容。先确认文件在哪个目录，以及仓库是否已被信任。问题几乎总是出在这里。