为什么 Codex 会跳过你编写的指令
每个目录一个文件，且覆盖文件总是胜出
Codex 在启动时会构建一个指令链，并具有文档记录的优先级。在全局级别，在你的 Codex 主目录中——“默认为 ~/.codex，除非你设置了 CODEX_HOME”——它“如果存在 AGENTS.override.md 则读取它。否则，Codex 读取 AGENTS.md。Codex 在此级别仅使用第一个非空文件。”
然后是项目范围：从项目根目录开始，向下遍历到你的工作目录，“在路径上的每个目录中，它会检查 AGENTS.override.md，然后是 AGENTS.md，然后是 project_doc_fallback_filenames 中的任何备用名称。Codex 每个目录最多包含一个文件。”
最后那句话就是整个失败的根源。AGENTS.override.md 并不会与它旁边的 AGENTS.md 合并——而是会替换它。文档将预期的用途描述为临时的：“当你需要临时全局覆盖而不删除基础文件时，请使用 ~/.codex/AGENTS.override.md。移除覆盖以恢复共享引导。”临时文件往往会变成永久文件，六个月后，没人会记得仓库的实际规则正被某人在某次事件中提交的覆盖文件所压制。
搜索在你启动的地方停止，因此更深的内容是不可见的
“从项目根目录（通常是 Git 根目录）开始，Codex 向下遍历到你当前的工作目录。”并且：“Codex 一旦到达你当前目录就会停止搜索，因此请将覆盖文件放置在尽可能靠近专业工作的地方。”
请将此视为一种约束，而不是建议。如果你从仓库根目录运行 Codex，那么 services/payments/ 内部精心编写的 AGENTS.md 就不在链中——你处于它的上方，而不是下方。同级目录也永远不会在链中。加载的文件集是一条单一的垂直路径，而具体是哪条路径完全取决于你启动时所处的位置。
还有一个相关的空白：“如果 Codex 找不到项目根目录，它只检查当前目录。”
链是有上限的，且两个官方页面对该上限的描述不同
“Codex 会跳过空文件，并在合并大小达到 project_doc_max_bytes（默认 32 KiB）定义的限制时停止添加文件。”随后的建议很具体：“达到上限时，提高限制或将指令拆分到嵌套目录中。”
值得指出这种不一致性，而不是假装它不存在。高级配置页面将相同的设置描述为“从每个 AGENTS.md 文件中读取多少内容”，而 AGENTS.md 页面则将其描述为合并大小的停止点。这两者并不是同一个规则。将 32 KiB 视为你可以达到的真实上限，并使用下面的 dump 命令验证结果，而不是从这两句话中进行推论——这就是“Instructions truncated”（指令被截断）故障排除条目存在的原因。
无论哪种方式，截断都是静默发生的，并且它会截掉链的末端：最靠近你工作目录的文件，而这些正是你最需要的特定文件。
不在列表中的文件名就不存在
Codex 读取 AGENTS.override.md、AGENTS.md 以及你在 project_doc_fallback_filenames 中列出的任何内容。你可以扩展它：
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536有了这个配置，“Codex 会按以下顺序检查每个目录：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。”然后是关键的一行：“不在此列表中的文件名在指令发现中会被忽略。”
这意味着 CONTRIBUTING.md、CLAUDE.md、.cursorrules 和 .github/copilot-instructions.md 默认情况下对 Codex 都是不可见的。在使用了多个智能体的仓库中，这是该问题最常见的版本：指令存在，它们很好，但它们位于一个 Codex 永远不会打开的文件中。关于文件标准问题的跨工具版本，在将你的 CLAUDE.md 迁移到 AGENTS.md中有详细介绍。
链只构建一次，因此在会话中期进行编辑不会改变任何事情
“Codex 在启动时构建指令链（每次运行一次；在 TUI 中，这通常意味着每个启动的会话一次）。”并且，来自验证指南：“如果指令看起来过时，请在目标目录中重新启动 Codex。Codex 在每次运行（以及每个 TUI 会话开始时）都会重建指令链，因此无需手动清除缓存。”
因此，自然的调试举措——发现 Codex 忽略了一条规则，更着重地添加该规则，然后再次询问——在同一个会话中是无法起作用的。你正在编辑一个已经被读取过的文件。重新启动才是解决方法，一旦你了解了这一点，它的成本就很低。
空文件，以及你忘记设置的 CODEX_HOME
故障排除列表中的两个快速项。“Codex 忽略空文件”——由工具创建但从未填写的占位符 AGENTS.md 仍然占用其目录的唯一槽位。以及：“Profile confusion（配置混淆）： 在启动 Codex 之前运行 echo $CODEX_HOME。非默认值会使 Codex 指向与你编辑的目录不同的主目录。”如果包装脚本或特定于项目的自动化配置设置了它，你的全局文件就不在你认为的地方。
人们的尝试
用更强烈的语气重写规则。 这可以理解，但如果文件根本没有加载，那就无济于事。在检查措辞之前，先检查加载情况。
将所有内容移入一个巨大的根目录 AGENTS.md。 这确实打破了每个目录一个文件的规则，但它会直接撞上 32 KiB 的上限。文档指向了相反的方向：拆分到嵌套目录中。
每次运行时在提示词中重复该约束。 有效，且是永久性的，但每次都要付出相同的成本——这就是如何停止向 AI 重复解释上下文中所描述的循环。
一看到覆盖文件就删除。 有时是对的，有时会删掉原本刻意设置的规则。先阅读里面的内容。
假设指令具有强制性。 它们只是第一轮对话中包含的引导。对于每次都必须遵守的规则，CI 检查才是保证——这也是为什么智能体会忽略你编写的指令文件中的核心观点。
将 CLAUDE.md 软链接到 AGENTS.md 并寄予希望。 将文件名添加到 project_doc_fallback_filenames 才是文档记录的途径，而且只需一行代码。
解决方法：询问 Codex 它加载了什么，然后扁平化
两个命令和一个清理步骤。首先停止猜测。
从仓库根目录导出链。 文档记录的检查方法：
codex --ask-for-approval never "Summarize the current instructions."“Codex 应该按照优先级顺序回显来自全局和项目文件的引导。”如果你编写的规则不在摘要中，那么问题出在“发现”上，而不是“遵守”上——你刚刚为自己节省了一个下午的提示词工程时间。
从你实际工作的目录中再次导出。 因为链取决于你启动的位置：
codex --cd services/payments --ask-for-approval never "Show which instruction files are active."文档将预期输出描述为“首先是全局文件，其次是仓库根目录的 AGENTS.md，最后是 payments 覆盖文件”。将此与你认为应该加载的内容进行对比。其中的差距就是你的 Bug 所在。
如果你想要记录而不是散文，可以获取日志。 “要审计 Codex 加载了哪些指令文件，请通过 codex -c log_dir=./.codex-log 启用纯文本 TUI 日志，并检查 ./.codex-log/codex-tui.log，或者如果你启用了会话日志，请检查最新的 session-*.jsonl 文件。”同时确认工作区：“验证你是否处于预期的仓库中，并且 codex status 报告了你期望的工作区根目录。”
然后按以下顺序进行清理。 找到仓库和 ~/.codex 中的每一个 AGENTS.override.md，确定这种压制是否是刻意的，并将非刻意的进行合并与删除。将任何其他智能体的指令文件名添加到 project_doc_fallback_filenames 中，使它们不再处于不可见状态。将任何接近 32 KiB 的内容拆分到嵌套目录中，而不是提高限制然后遗忘。删除空指令文件，使其不再占用槽位。并检查 echo $CODEX_HOME。
这可以让你的指令成功加载。但它无法解决的是，链是有意被限制上限的。一旦发现机制正确，你就在你工作的每个目录中分配 32 KiB 的预算——而首先被挤出的总是同一类内容：为什么存在某种约束、之前尝试过什么、拒绝了哪种方法以及原因。规则在筛选中幸存下来，而推理过程却没有。
这正是 MemoryLake 的用武之地：将你项目的持久知识保存在工具读取的图层中，从而使指令文件保持精简，同时保留推理过程。设置只需三个步骤。
步骤 1：创建 API 密钥
登录 MemoryLake 并创建一个 API 密钥。一个凭据即可连接你使用的所有工具。
步骤 2：上传你的第一批记忆
简短的条目，每条包含一个主张。哪些内容应该放在链外而不是链内：
附带原因的约束。 “Payments 使用 make test-payments，因为 npm 脚本不会启动沙箱存根。”AGENTS.md 中的一行声明了该命令。只有附带原因，才能阻止别人因认为其多余而将其删除。
在此代码库中已被拒绝的方法。 这类内容在指令文件中无处安放，却在每次全新运行中都会被重新提议。
没有任何声明的环境事实。 未记录的速率限制、仅在 CI 中失败的测试、两个迁移之间的顺序要求。
来自事件的决策。 覆盖文件最初存在的原因，以便下一个人能够区分刻意的压制与遗留的垃圾。
步骤 3：连接你的 AI 和智能体
连接你使用的工具。MemoryLake 可以通过 MCP 和 API 访问，因此支持 MCP 的原生智能体（包括 Claude Code、Codex 和 OpenClaw）可以通过指向 MCP 服务器进行连接，而其他助手则通过 API 读取相同的记忆。实际效果是，你检索的内容不会占用指令预算，因为它不会在第一轮对话中发送。
三个坦诚的限制。MemoryLake 不会编写你的 AGENTS.md 文件，也不会改变 Codex 发现它们的方式——上述六种机制是 Codex 的，解决方法完全在你自己。它只保存你或你的智能体放入其中的内容，因此步骤 2 是手动的。此外，指令是引导而非强制配置；记忆层不会改变合规性，对于硬性要求，CI 仍然是解决方案。
这在实践中带来了什么改变
“它忽略了我的规则”变成了一个只需一条命令就能解答的问题。 让 Codex 总结其当前的指令。你的规则要么在列表中，要么不在，这两种情况有完全不同的解决方法。
覆盖文件不再是地雷。 一旦扁平化，就不会在十一月重新发现被遮蔽的文件。
指令文件变得更小。 链之所以逐渐逼近 32 KiB，是因为它在承担两项工作。将它们分开，上限就不再是约束。
其他智能体的文件不再是累赘。 在 config.toml 中添加一行，你团队已经维护的 CLAUDE.md 或 TEAM_GUIDE.md 就会开始发挥作用。
重新启动成为一种条件反射。 链在每次运行中只构建一次。了解这一点可以将令人困惑的会话变成五秒钟的修复。
让 Codex 真正加载 AGENTS.md 的最佳实践
在编辑任何内容之前导出链。 让 Codex 总结其当前的指令，分别从根目录和你的工作目录进行。
永远不要保留永久的 AGENTS.override.md。 它会压制它旁边的文件，且文档将其定位为临时的。
从你想要应用规则的目录启动。 链在你当前的工作目录停止；更深的文件永远不会加载。
在接近上限时进行拆分，而不仅仅是提高上限。 嵌套目录是达到 project_doc_max_bytes 时文档记录的补救措施。
在 project_doc_fallback_filenames 中列出每个其他智能体的指令文件名。 不在列表中的文件名在指令发现中会被忽略。
删除空指令文件。 空文件会被跳过，但它仍然占用其目录的唯一槽位。
编辑后重新启动。 指令链在每次运行中只构建一次，因此会话中期的编辑不会生效。
当全局文件似乎不起作用时，检查 echo $CODEX_HOME。 非默认值会指向与你编辑的目录不同的主目录。
将推理过程排除在链之外。 指令是有上限且始终开启的；规则背后的论据才是让智能体能够处理你未写下的情况的关键——这也是为什么 RAG 不是记忆中的普遍问题。
结论
Codex 在如何寻找指令方面异常明确，这使得这是一个可以解决的问题，而不是一个神秘的谜团。It 每个目录最多读取一个文件，其中 AGENTS.override.md 优于 AGENTS.md。它从项目根目录向下遍历到你的工作目录并在此停止。它以根目录优先的方式进行拼接，并在合并大小达到 project_doc_max_bytes（默认 32 KiB）时停止添加。它会忽略不在发现列表中的文件名、忽略空文件，并且每次运行只构建一次完整的链。
六种机制，全部是静默的，但通过让 Codex 总结它加载的指令，每一种都可以在大约十秒钟内显现出来。从根目录和你实际工作的目录中执行此操作，扁平化那些本应是临时的覆盖文件，将你其他智能体的文件名添加到备用列表中，并在接近上限时进行拆分而不是任其增长。
然后将约束、事件和被拒绝的方法放在一个你可以查询的图层中，而不是在第一轮对话中就发送的图层中——这样指令链就能保持足够小以完全加载，并且在关键时刻推理过程仍然存在。