Codex 不读 AGENTS.md？从启动目录到规则验证的实操教程

本文适用范围与核对依据

本指南由 AIXiamo（AI夏末）整理，面向已经安装 Codex CLI、希望让它遵循项目约定的用户。内容按 2026 年 9 月 8 日的 OpenAI 官方文档核对，命令参数与本地 Codex CLI 0.153.4 的帮助信息交叉检查。

下面的标记示例用于检查启动时的项目指令发现。示例列出的输出是预期结果，实际加载与执行情况需要在自己的环境中验证。App、CLI、远程任务或 worktree 的工作目录不同，先确认正在检查的是哪一份项目。

一、先看目录，再看文件内容

先在准备启动 Codex 的同一个终端执行下面两条命令。第一条用于记录版本；第二条显示当前 Git 项目根。另用 macOS / Linux / WSL 的 pwd，或 Windows PowerShell 的 Get-Location 查看当前目录。若 Git 提示不在仓库中，先确认目录是否正确，不要为了消除报错就在业务目录随意初始化仓库。

在默认项目根识别规则下，Git 根是启动发现的重要边界。官方还支持 project_root_markers 等配置，因此使用自定义配置时，应结合实际项目根判断。

codex --version
git rev-parse --show-toplevel

二、AGENTS.md 与 AGENTS.override.md 怎样组合？

按官方 AGENTS.md 专项说明，Codex 启动时先读取全局指令。全局目录默认为 ~/.codex，设置 CODEX_HOME 时以该值为准；这里先检查 AGENTS.override.md，再检查 AGENTS.md。随后在项目范围内，沿项目根到当前工作目录选择并合并文件；找不到项目根时，项目范围只检查当前目录。

项目范围内的每个目录按 AGENTS.override.md、AGENTS.md、已配置的候选文件名依次寻找非空文件。同一目录最多取一个；跨目录仍会合并，更靠近工作目录的规则用于处理较早规则的冲突。子目录的 override 不等于删除所有父目录约定。

这里描述的是启动发现，不能推导为任务执行期间绝不会再读取更深层的规则，也不要假设一次 cd 就能使现有会话重新加载全部指令。排查时直接从目标目录启动一个新会话，结果更容易比较。

example-project/
├── .git/
├── AGENTS.md
└── docs/
    ├── AGENTS.md
    └── AGENTS.override.md

# 从 docs 启动时，本例的项目文件选择：
# example-project/AGENTS.md
# example-project/docs/AGENTS.override.md
# docs/AGENTS.md 不会在同目录同时追加

三、用一个最小项目检查规则是否加载

新建一个专用的空白示例目录 example-project，在该目录执行 git init，然后新建 docs 子目录。不要把下面的标记规则粘贴进正在工作的业务项目。

按下方标注的路径分别保存三个文件，不要将整段放进同一份 AGENTS.md。根文件定义项目标记和默认检查命令；docs 的两个候选文件刻意给出不同标记，便于观察 override 的选择结果。这里仅询问命令文本，不要求实际运行任何测试。

# 文件：example-project/AGENTS.md
# Example project rules
- 项目标记：ROOT_DEMO
- 本例默认检查命令：npm test

# 文件：example-project/docs/AGENTS.md
# Docs rules
- 目录标记：DOCS_NORMAL

# 文件：example-project/docs/AGENTS.override.md
# Docs override
- 目录标记：DOCS_OVERRIDE
- 本目录默认检查命令：npm run docs:check

四、用两个新会话比较预期结果

先停留在 example-project 根目录运行第一条命令。退出该 CLI 会话后，再从同一终端运行第二条命令。--cd docs 指定第二次运行的工作目录；--sandbox read-only 限制模型通过工具改写工作文件。

根目录运行预期复述 ROOT_DEMO 与 npm test；docs 目录运行预期保留 ROOT_DEMO，使用 DOCS_OVERRIDE，并将本目录检查命令识别为 npm run docs:check。如果出现 DOCS_NORMAL，优先核对 override 的拼写、实际路径和内容是否为空。

这只是一个诊断信号。如果回答遗漏或矛盾，继续检查实际文件与配置，不把模型的一句“已经读取”视作证明。

codex --sandbox read-only "不要调用工具或修改文件。仅依据已加载的项目规则，列出项目标记、目录标记（如果有）和默认检查命令。"

# 退出上一个会话后，从 example-project 根目录运行：
codex --cd docs --sandbox read-only "不要调用工具或修改文件。仅依据已加载的项目规则，列出项目标记、目录标记（如果有）和默认检查命令。"

五、目录正确仍不生效，继续查哪些地方？

检查文件是否误存为 AGENTS.md.txt、是否只有空白内容，以及当前运行是否使用了另一个 Codex 主目录。配置、全局规则和工作项目要属于同一套运行环境。

project_doc_max_bytes 默认值为 32768，单位是字节。超长指令存在截断风险；先精简重复背景，把关键命令和验收条件写清楚，再验证实际加载结果。不要假设每份文件都能额外获得一个独立的 32 KiB 配额。

修改规则或发现参数后，用新运行复核。若设置没有生效，还要检查更高优先级的配置覆盖；不要只反复编辑一份未被当前运行采用的 config.toml。相关参数见文末的官方高级配置与配置优先级说明。

• 同目录出现 override 时，先读它的具体内容，再决定是否需要调整。
• 检查命令要真实存在于项目中；文档写了 npm test，不代表项目一定定义了 test 脚本。
• 指令文档可以约定工作方式，不能代替权限设置、凭证管理和程序校验。

六、规则读到了，怎样验证它真正执行？

将“认真测试”改成可以核对的约定，例如“修改解析函数后，运行项目已有的解析测试；报告执行命令、退出结果和未覆盖情况”。命令名称应来自实际项目，不照搬示例中的 npm 脚本。

对一次小修改，分别检查修改范围、测试输出和最终说明。下面的 Git 命令用于查看工作区差异及空白错误；它们不能代替功能测试。若有新建文件，也要在 status 中逐个核对。

出现未遵守规则的情况，应先找出是哪一项没有完成及其原因。只有读到文件、指令没有冲突、执行条件可用，仍无法达到验收要求时，才继续评估任务拆分或提示方式。

git status --short
git diff --stat
git diff --check
git diff

# 随后运行该项目已定义、与修改相关的实际测试命令