Codex CLI 写了 AGENTS.md 当前目录不遵守？先按这 4 步排查

阿沐沐，

213人浏览 · 2026-09-04 18:38:51

阿沐沐， · 2026-09-04 18:38:51 发布

Codex CLI 写了 AGENTS.md 当前目录不遵守？先按这 4 步排查

已经写了 AGENTS.md，Codex 在当前目录就是不听里面的约定。先别急着改文件，大概率不是内容的问题。

先做三件事：

关掉当前 Codex，重新打开一次；
看当前目录有没有 AGENTS.override.md 挡在 AGENTS.md 前面；
确认你是在目标项目目录启动 Codex。

这三步走完还没解决，再按下面 4 步排查。

先交代版本：本文按 Codex CLI 0.147.0 说明，最后核验日期 2026-08-20，免得你对着旧版字段白忙一场。下面的命令以 PowerShell 为主；从 Bash 或 Zsh 启动 Codex 的话，对应命令见文末参考文档。

文件在，不代表这次一定生效

磁盘上有 AGENTS.md，只说明这个位置符合候选条件，离真正生效还隔着几道关：

文件存在
  → 这一层实际采用哪一份
  → 从根到当前目录合并
  → 新会话读取
  → 行为变化

常见的卡点就这几个：

同目录有一份 AGENTS.override.md，它排在 AGENTS.md 前面；
实际被采用的那一份是空的，这一层什么约定都没贡献；
更近的子目录另有约定，把根上的内容盖住了；
当前窗口还是旧会话，启动时没有重新读文件。

所以这时候继续改内容没有用，先确认这一层到底会用哪一份才行。

第一步：列出这一层实际会用的文件

这一步是分水岭：要么你写的那份根本没被采用，要么已经被采用、问题出在后面。两种情况的解法完全不同。

请在准备启动 Codex 的同一个 PowerShell 窗口里操作，换一个窗口查到的环境变量可能不一样。

先看全局目录

没设置 CODEX_HOME，全局目录就是 ~/.codex/。这里的 ~ 指当前用户的主目录，在 PowerShell 里跑一下 $HOME 就能看到实际路径，Windows 上通常是 C:\Users\<你的用户名>。设置过 CODEX_HOME，就看那个目录，并且这个目录必须已经存在。

$codexHome = [Environment]::GetEnvironmentVariable('CODEX_HOME', 'Process')
if ($null -eq $codexHome) {
  $codexHome = Join-Path $HOME '.codex'
}
@('AGENTS.override.md', 'AGENTS.md') | ForEach-Object {
  $path = Join-Path $codexHome $_
  if (Test-Path -LiteralPath $path -PathType Leaf) {
    $path
  }
}

在全局目录里，AGENTS.override.md 排在 AGENTS.md 前面。全局的 AGENTS.override.md 要是空文件或纯空白，就会回退到全局的 AGENTS.md。

再看项目目录

项目目录不适用上面那条“空文件回退”规则，这是两套行为，别记混。

先找到项目根。有 Git 的话运行：

git rev-parse --show-toplevel

这是跨平台 Git 命令，作用是打印仓库根路径，不是 Codex 找文件的内部步骤。命令失败时，就按你实际配置的项目根标记手工向上找，默认标记是 .git。只有确认没有任何标记、或标记列表为空时，才只检查当前目录。

从项目根开始，沿着你当前所在的路径一层层往下查。每一层只留一份，顺序是：

AGENTS.override.md
→ AGENTS.md
→ 你配置过的备用文件名

在某一层列出文件时，PowerShell 可以运行：

@('AGENTS.override.md', 'AGENTS.md') |
  Where-Object { Test-Path -LiteralPath $_ -PathType Leaf }

默认没有任何备用文件名，只有写进 project_doc_fallback_filenames 的名字才会参与。同层一旦已经有 AGENTS.override.md 或 AGENTS.md，备用名就不会被采用，这点容易忽略。

打开这一层实际采用的那份文件，看它是不是空的。这里有个坑：Codex CLI 0.147.0 里，全局和项目对空覆盖文件的处理不一样，

全局目录：空的 AGENTS.override.md 会回退到 AGENTS.md；
项目目录：如果先采用了空的 AGENTS.override.md，这一层就不会再改用同层的 AGENTS.md。

换句话说，项目目录里只要留了一个空的 AGENTS.override.md，旁边那份写好的 AGENTS.md 就不会被这一层采用。处理方式：删掉不需要的空覆盖文件，或者把有效内容写进实际被采用的那份。

临时改名排查，先保存原内容，看完记得恢复。

到这里，把每一层实际采用的文件按“从项目根到当前目录”排好，再加上全局那份，就是本次排查要对照的文件顺序。不过它仍然只是文件选择结果，不代表这次运行已经读过。

第二步：看更近的目录有没有盖住前面的约定

文件都在最终顺序里，根上的约定却像没被遵守？通常是更近目录里有一份同主题约定把它盖住了。

只比较真正冲突的主题就行。没有冲突就停，不要把每个子目录的文件都当成覆盖。

项目文件从根一路合并到当前目录，越近的排得越靠后。同一主题起了冲突，更近的约定生效。

拿一个常见的例子来说：

根目录写：改完 JavaScript 后跑 npm test；
services/payments/ 写：测试用 make test-payments。

你在支付目录下开工时，起作用的就是后面那句。要改就去改真正负责这个范围的最近文件，在多个目录里重复粘贴同一句只会越改越乱。

找到获胜的更近约定，再进下一步。

第三步：记下项目信任状态，但先别改

路径和内容都核对过了，接下来看项目的信任状态。

目前官方能确认的是：未信任的项目会跳过项目 .codex/ 目录下的配置、hooks 和 rules。至于未信任会不会连项目层的 AGENTS.md 一起跳过，官方没有说明，需要你在自己的环境中验证。.codex/ 的门禁不能直接当成 AGENTS.md 的门禁。

打开全局目录下的 config.toml，查找这个项目路径对应的 trust_level，记下它是 trusted、untrusted，还是根本没有这一项。

检查时只读就行，别为了排错把陌生仓库改成 trusted。

记下之后，保存你对指导文件的修改，然后新开一次会话。

第四步：改完后新开一次会话

已经打开的窗口还在按旧约定行动，不一定是文件改错了——当前窗口用的很可能还是启动时构建好的那份约定。

官方的说法是：这些约定在每次运行开始时构建一次；在交互界面（TUI）里，这通常对应一次启动会话。

正确做法是：

保存修改；
结束当前 Codex 运行；
从目标项目目录重新启动 Codex，或打开一次新的交互界面会话。

别用已经打开的窗口判断结果，也不用去清一份并不存在的手动缓存。

新会话按预期行动了，排查到这里就可以停。

如果还是不行：按现象查

前面的步骤都做了，新会话也开了，行为还是不对。这时候只看你实际遇到的那个现象，不用把下面全部走一遍。

后面的文件或文件后半段像是没带上：按合并顺序看项目文件有多长，对照 project_doc_max_bytes，默认合并上限是 32 KiB。Codex CLI 0.147.0 会按剩余预算依次累计，超出的项目文件直接截断。上限设成 0 的话，项目文档就完全不加载。确认触及上限后，再调整内容位置或上限，别继续猜模型行为。
用的不是 AGENTS.override.md / AGENTS.md 这类默认名字：核对名字有没有写进 project_doc_fallback_filenames，同层有没有更高优先级的文件。拼写不一致就不会被当成候选。
看到 managed、requirements 或组织来源的提示：记录来源后停止本地绕过。它会不会改变这次用哪些指导文件，需要你在自己的环境里验证。
启动目录、CODEX_HOME 或 CLI 入口对不上：在启动用的那个终端里核对当前目录、CODEX_HOME、CLI 入口和版本，换过窗口就重查一遍。
文件顺序对了、新会话也开了，还是拿不准这次运行读没读：走官方核验入口，模型的复述不能当成唯一依据。官方提供的 summarize 一类提示会发出真实模型请求，不是主路径。交互界面里的 /status 是斜杠命令，要在 Codex 交互界面里输，拿到 PowerShell 里执行是没用的。里面可能出现 Agents.md 字段，但它不能直接当作“当前已读取”的证据，目前最多算一条待核对的线索。