Codex 到哪里查找 AGENTS.md
启动时,Codex 会构建一条指令链:先是一个全局文件,然后是沿着路径一直到你工作文件夹的各个项目文件。
1. 你的全局文件。 位于 Codex 主文件夹 ~/.codex(或由 CODEX_HOME 设置的文件夹)中。如果存在 AGENTS.override.md,Codex 就使用它,否则使用 AGENTS.md。这里只使用一个文件。
2. 你的项目。 Codex 从项目根目录开始(默认是 Git 根目录;可用 project_root_markers 更改),一路向下走到你正在工作的文件夹。在每个文件夹中,它最多取一个文件,按以下顺序检查:
AGENTS.override.mdAGENTS.md- 你在
project_doc_fallback_filenames中列出的任何名称
如果没有项目根目录,Codex 只检查当前文件夹。
这些文件如何合并
Codex 从根目录开始向下连接这些文件,文件之间用空行隔开。离你的工作文件夹更近的文件排在后面,因此它的指令优先于前面的指令。空文件会被跳过。
存在大小限制:当这些文件的总大小达到 project_doc_max_bytes 时,Codex 就停止添加文件,默认值为 32 KiB(32,768 字节)。如果你的指令很长,请提高该限制,或者把它们拆分到子文件夹中的 AGENTS.md 文件里。
这两项设置都位于 Codex 主文件夹的 config.toml 中(默认是 ~/.codex/config.toml):
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536
更改之后,请重新开始一次 Codex 运行。
一个简单的 AGENTS.md
# AGENTS.md
## Commands
- Build: `npm run build`
- Test: `npm test`
## Rules
- Write plans to `docs/plans/<task>.md` before changing code.
- Keep each change small; explain it in the pull request.
Codex 不会自行把计划保存到文件。要得到以后可以阅读的计划,请让它把计划写入文件,可以写在 AGENTS.md 中(如第二条规则),也可以写在你的提示中。
阅读 Codex 写出的内容
文件不多时,任何编辑器都可以。文件很多时(每个任务一份计划,加上笔记和报告),把它们当作页面来读,并看到哪里改了,会很有帮助。
在 Mac 上,用 PilcrowMD(免费,测试版):
- 在我的文件夹中添加你的项目文件夹。Codex 写入的文件会显示出来,并标有 N(新)或 U(已更新)。当 Codex 或其他应用更改了已打开的笔记时,它会重新载入。
- 高亮显示更改会显示 Codex 在你已读过的计划中改了什么:添加的为蓝色,删除或编辑的为橙色。
- 并排比较会显示两个版本,可按页面,也可按源码。
- 开启文件历史记录后,文件 › 显示历史记录… 可让你回到较早的版本。
- 表格、代码块、任务列表和 Mermaid 图表都会绘制成页面。无需互联网连接。
PilcrowMD Mac 版(测试版) · 更多关于阅读智能体文件的内容
常见问题
AGENTS.md 只给 Codex 用吗? 不是。它是一种开放的约定,多个编程智能体都会读取,而不是 Codex 专用的格式。例如,当项目没有 CLAUDE.md 时,Claude Code 可以读取 AGENTS.md(Claude Code 页面)。
为什么 Codex 忽略了我的一部分指令? 请检查大小限制(默认 32 KiB),以及同一文件夹中的 AGENTS.override.md 是否取代了你的 AGENTS.md。
我能在手机上阅读这些文件吗? 如果项目文件夹同步到 Google Drive,请在 PilcrowMD Android 版的“我的文件夹”中添加它。打开笔记即可看到最新版本;Android 上没有实时重新加载。
Mac 上同样可用: PilcrowMD Mac 版(测试版)