Codex CLI AGENTS.md 怎么放：全局、仓库和子目录的区别

Windows 上刚能启动 Codex CLI 时，工作约定最容易写错地方：有人塞进 config.toml，有人只在仓库根放一份 AGENTS.md，进到 services\payments 这类子目录后又不知道还会不会带上。

AGENTS.md 是 Codex 开始工作前读取的指导文件。个人习惯默认写在 ~/.codex/AGENTS.md，整个仓库写在项目根，某个服务再在那个子目录另放一份。这里的 ~ 表示当前用户的主目录；在 PowerShell 里运行 $HOME 就能看到实际路径，Windows 上通常是 C:\Users\<你的用户名>。

本文按 Codex CLI 0.147.0 说明，最后核验日期为 2026-08-14。读完后应能判断三层各放哪一份，并在自己选定的目录里列出候选文件。这份清单只能确认文件发现路径，不能证明当前会话已经加载。

你想约束的范围	默认放哪
每个仓库都带上的个人约定	~/.codex/AGENTS.md；需要临时覆盖时用同目录的 AGENTS.override.md
整个仓库共用的约定	项目根的 AGENTS.md
某个服务或模块自己的约定	该子目录的 AGENTS.md，或同目录的 AGENTS.override.md

AGENTS.md 是什么

AGENTS.md 保存的是你希望每次开工都先看见的工作约定，不是这次对话里随口说的一句话。换一个仓库再启动，文件还在原来的位置。适合写进去的是短约定：这个仓库用哪条检查命令、改了公开接口要不要补文档、哪些事要先问过再做。

下面是按官方文档仓库根示例整理的一份文件，经过翻译和重排，不是官方原文，也不是本机实测，不要求照抄：

# AGENTS.md

## 仓库期望

- 开 pull request 前跑 `npm run lint`。
- 改了公开工具的行为时，把说明写进 `docs/`。

文件就是这样一份普通 Markdown。全局和子目录各放哪一份见后面；仓库根示例只在这里完整出现一次。

它和 config.toml、Skill 有什么不同

config.toml 保存模型、审批、沙箱等设置，管的是“默认怎么跑”。AGENTS.md 管的是“在这个目录里按什么约定做事”。模型 ID、审批策略继续留在配置文件里，不要为了省事写进指导文件。

Skill 是另一类可复用能力文件，发现方式不同，另篇再讲。本篇只处理 AGENTS.md 这份持久约定，以及它在全局、仓库和子目录各放哪一份。

这些约定不会在你改完磁盘后，自动灌进已经打开的窗口。官方说明指令链在每次运行开始时构建一次；在交互界面（TUI）里，这通常对应一次启动会话。改完 AGENTS.md 或同层覆盖文件后，要新开一次运行或交互界面会话，才会重新读取。

全局、仓库根、子目录分别放哪

按你希望约束的范围选位置，不要先比较哪一份看起来更高级。开头的对照表已经按范围列过默认路径。

全局那一份跟着当前系统用户走，不会自动共享给这台电脑上的其他人，也不会自动写进某个 Git 仓库。适合放“我这个人在这台电脑上的习惯”，例如提交前先跑测试、不要强推共享分支。某个仓库自己的测试命令、包管理器或目录结构，不要写在这里。

需要临时改全局约定时，另放 ~/.codex/AGENTS.override.md。它是同层的临时覆盖文件，不是第二套配置，也不必删除原来的 AGENTS.md。全局这一层只取第一份非空文件：有内容的覆盖文件优先；空的或纯空白的 AGENTS.override.md 不会盖住有内容的 AGENTS.md。用完删掉覆盖文件，就会回到基础文件。

当前进程里如果设置了 CODEX_HOME，全局文件就不在默认的 ~/.codex/ 下，而在那个目录里。这个值可能来自当前终端、启动脚本或父进程，而且这个目录必须已经存在。不要用另一个环境里的同名路径，推断当前终端实际读取的位置。

仓库约定不是“只写在仓库根”。Codex 先从当前工作目录向上找项目根，默认是含 .git 的那一层；找不到根，或者把项目根标记配成空列表时，只看当前目录。确定根之后，再从该根一路收到你现在所在的目录。你站在子目录里启动 Codex，不会只读根上那一份。

整个仓库共用的约定，写在项目根的 AGENTS.md。某个服务或模块自己的约定，写在那个子目录的 AGENTS.md，或者同目录的 AGENTS.override.md。子目录这份同样是指导文件：覆盖文件只是同层临时覆盖，不是另一种配置格式。

多层文件怎样合并

每个目录最多纳入一份，顺序是：AGENTS.override.md → AGENTS.md → 你另外配置过的备用文件名。默认没有备用名。空文件不进入合并。

合并时从项目根拼到当前目录。更靠近当前目录的文件出现在后面，因此覆盖更早的约定。同一个主题上，子目录那一份会盖住更早的约定。

下面是官方文档里的整理案例，不是本机实测树，也省略了仓库里其他文件：

仓库根/
  AGENTS.md
  services/
    payments/
      AGENTS.override.md

官方文档同时给出了这三份文件的示例正文。下面按该示例翻译整理，不是原文快照，也不要求照抄。仓库根那一份沿用上文的仓库根示例，这里只补另外两层。

全局默认，放在 ~/.codex/AGENTS.md：

# ~/.codex/AGENTS.md

## 工作约定

- 改完 JavaScript 文件后跑 `npm test`。
- 安装依赖优先用 pnpm。
- 新增生产依赖前先问过我。

支付目录覆盖，放在 services/payments/AGENTS.override.md：

# services/payments/AGENTS.override.md

## 支付服务规则

- 测试用 `make test-payments`，不要用 `npm test`。
- 不要在未通知安全渠道的情况下轮换 API 密钥。

你在 services/payments/ 开工时，项目层会先带上仓库根那一份，再带上支付目录这份覆盖；全局那一份仍按上一节的路径另外读取。更近的“测试用 make test-payments”出现在后面。

当前目录不同，项目层列入发现清单的文件也不同：

• 停在仓库根：只有根上的 AGENTS.md。
• 停在 services/：仍然只有根上那一份，因为这一层没有候选文件，不会贡献约定。
• 停在 services/payments/：根上的 AGENTS.md，再加上这个支付目录的 AGENTS.override.md。后者更近，出现在后面。

如果你另外配置过备用文件名，每个目录只有在没有覆盖文件和 AGENTS.md 时才会看那些名字。文件特别多或特别长时，后面的约定可能带不上；那不影响本篇先判断文件该放哪一层。

在当前目录列出候选文件

主路径是看磁盘上实际有哪些文件，不是先让模型做摘要。列出来的是按当前目录、候选顺序和已知配置推导出的发现清单：这些文件会被当作这一层的候选，但不能单独证明这次运行已经读入、没有被体积上限截断，或项目文档没有被关掉。

选定你准备启动 Codex 的那个目录。先从这个目录向上找，直到看到含 .git 的目录，那就是默认的项目根。找不到时，还不要立刻只看当前目录。默认标记是 .git；如果你改过项目根标记，按实际配置的标记向上找，不要只认 Git 命令。

从项目根开始，沿着走进来的每一层，看有没有 AGENTS.override.md 或 AGENTS.md。每个目录只记一份：先覆盖文件，再 AGENTS.md，再你配置过的备用名。空文件跳过，这一层不贡献约定。把留下的文件按“从根到当前目录”排好。全局那一份另外列：默认是 ~/.codex/AGENTS.md 或同目录的覆盖文件；当前进程设置了 CODEX_HOME 时，改列那个目录里的对应文件。

有 Git 时，可以在当前目录先打印项目根：

git rev-parse --show-toplevel

看到仓库根路径，就按上面的办法往当前目录列文件。这个命令只是找根的便捷方式，不是 Codex 内部的发现算法。命令失败时，按实际配置的项目根标记手工向上查找。只有确认没有任何标记，或标记列表为空时，才只检查当前目录。

在某一层列出候选文件时，PowerShell 可以用：

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

Bash 或 Zsh 可以用：

for f in AGENTS.override.md AGENTS.md; do
  [ -f "$f" ] && printf '%s\n' "$f"
done

这两条命令都只列出普通文件，同名目录不会算进去。看到文件名，只表示这一层存在候选；还要看它是不是空文件，以及同目录有没有更靠前的覆盖文件。没有输出时，这一层不贡献约定，继续看下一层。

用前面的官方整理案例走一遍。当前目录是 services/payments 时，项目层可以记成：

<仓库根>/AGENTS.md
<仓库根>/services/payments/AGENTS.override.md

<仓库根> 换成你自己找到的路径。仓库根取 AGENTS.md，services/ 没有候选，services/payments/ 取 AGENTS.override.md。全局那一份另外看 ~/.codex/ 里实际有没有非空文件。换到你自己的目录时，用同一套步骤，不要照抄这棵树。

还想对照当前会话时，可以在已经启动的交互界面里看 /status 的 Agents.md 字段，取值以当前会话为准。官方也提供过：

codex --ask-for-approval never "Summarize the current instructions."

这会发送一次真实模型请求。这条示例里的 never 只是官方示例使用的审批参数，不是本篇推荐的日常审批方式，也不是确认候选文件位置的必做步骤。/status 同样只是可选对照。

改完文件后要新开一次会话

改完磁盘上的 AGENTS.md 或覆盖文件后，已经开着的窗口继续用启动时构建好的那一份。要让新约定进入下一次工作，请退出当前 Codex 运行或交互界面会话，再从目标目录重新启动。

清单上没有文件时，这一层不会贡献约定。清单上已经有文件，但当前目录的行为没有按约定变化，下一步是查为什么没被遵守；那不是本篇要解决的对象定义问题。

常见误区

• 工作约定不要写进 config.toml。那份文件管模型、审批、沙箱等设置，不管“在这个目录里按什么约定做事”。
• 仓库约定不是只放在仓库根。你站在子目录里启动时，还会从项目根收到当前目录；某个服务自己的约定应写在那个子目录。
• AGENTS.override.md 不是第二套配置。它只是同层的临时覆盖文件，不必删掉原来的 AGENTS.md。

官方资料

• Custom instructions with AGENTS.md：说明 AGENTS.md 在开始工作前读取，以及全局和项目两层如何放置。
• Developers 文档：AGENTS.md：同一主题的 Developers 文档页。
• Project root detection：说明默认用 .git 向上找项目根，以及空标记时只看当前目录。
• Inspect the session with /status：说明 /status 用于查看当前会话摘要。

参考文档

站内版本提供完整且持续更新的三层示例和候选文件确认步骤，需要对照更完整的说明时可以看：

Codex CLI 的 AGENTS.md 是什么，全局、仓库和子目录各放哪一份