Codex 与 AGENTS.md:阅读 Codex 使用的文件

Codex 从名为 AGENTS.md 的 Markdown 文件中读取指令。当你提出要求时,它还可以把计划、规格说明和笔记作为 .md 文件写入你的项目。本页说明 Codex 到哪里查找 AGENTS.md,以及怎样舒适地阅读所有这些文件。

Codex 到哪里查找 AGENTS.md

启动时,Codex 会构建一条指令链:先是一个全局文件,然后是沿着路径一直到你工作文件夹的各个项目文件。

1. 你的全局文件。 位于 Codex 主文件夹 ~/.codex(或由 CODEX_HOME 设置的文件夹)中。如果存在 AGENTS.override.md,Codex 就使用它,否则使用 AGENTS.md。这里只使用一个文件。

2. 你的项目。 Codex 从项目根目录开始(默认是 Git 根目录;可用 project_root_markers 更改),一路向下走到你正在工作的文件夹。在每个文件夹中,它最多取一个文件,按以下顺序检查:

  1. AGENTS.override.md
  2. AGENTS.md
  3. 你在 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(免费,测试版):

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 版(测试版)