AGENTS.md 是 Codex 每次工作前都会自动读取的指令文件，类似于面向 AI 的 README。通过分层机制（全局 ~/.codex/AGENTS.md、仓库级、子目录级），你可以让 Codex 在不同项目里遵守不同的规则，而且离工作目录越近的规则优先级越高。本文覆盖发现机制、创建步骤、分层配置和排错方法。

AGENTS.md 使用指南

Codex 在每次启动时（TUI 每次启动一次会话）读取 AGENTS.md 文件，构建一个指令链，在开始任何工作之前先加载这些指导。

Codex 如何发现 AGENTS.md

Codex 按以下优先级顺序构建指令链：

1. 全局级：读取 ~/.codex/（除非设置了 CODEX_HOME 环境变量）目录下的 AGENTS.override.md，如果不存在则读取 AGENTS.md。同一层级只用第一个非空文件。

2. 项目级：从项目根目录（通常是 Git 根目录）开始，逐层向下走到当前工作目录。每个目录里依次检查 AGENTS.override.md、AGENTS.md，以及 project_doc_fallback_filenames 里配置的 fallback 文件名。每个目录最多包含一个文件。

3. 合并顺序：从根目录向下拼接文件，用空行分隔。靠近当前工作目录的文件出现在后面，优先级更高（因为它们在组合 Prompt 里位置靠后）。

大小限制：Codex 跳过空文件，组合大小达到 project_doc_max_bytes（默认 32 KiB）后停止加载。超过限制时可以提高阈值或把指令分散到子目录里。

---

创建全局指导

在 ~/.codex/AGENTS.md 里写个人默认值，让所有仓库都继承你的工作习惯：

mkdir -p ~/.codex

# ~/.codex/AGENTS.md

## 工作约定

- 修改 JavaScript 文件后必须运行 `npm test`
- 安装依赖时优先用 `pnpm`
- 添加新的生产依赖前先询问确认

验证是否生效：

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

Codex 会在提出建议之前先引用 ~/.codex/AGENTS.md 里的内容。

如果需要临时覆盖全局配置而不删除原文件，可以创建 ~/.codex/AGENTS.override.md。删除这个 override 文件就恢复原有全局指导。

---

分层管理项目规则

仓库级文件负责项目规范，在继承全局默认值的同时覆盖特定规则：

1. 仓库根目录创建基础 AGENTS.md：

# AGENTS.md

## 仓库规范

- 提 PR 前运行 `npm run lint`
- 改动行为时在 `docs/` 里更新对应公共函数的文档

2. 在需要特殊规则的子目录创建 AGENTS.override.md，比如 services/payments/：

# services/payments/AGENTS.override.md

## 支付服务规则

- 用 `make test-payments` 而不是 `npm test`
- 轮换 API key 前必须通知安全频道

3. 从子目录启动 Codex，确认加载顺序：

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

预期结果：Codex 先报告全局文件，再是仓库根目录 AGENTS.md，最后是 payments 目录的 override。

目录结构示例

AGENTS.md                    # 仓库规范（高亮）
services/
  payments/
    AGENTS.md                # 被忽略（因为 override 存在）
    AGENTS.override.md       # 支付服务规则（高亮）
    README.md
  search/
    AGENTS.md

---

配置 fallback 文件名

如果你的仓库已经用了其他文件名（比如 TEAM_GUIDE.md），可以把它加入 fallback 列表，Codex 会把它当作指令文件处理：

# ~/.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。不在这个列表里的文件名会被忽略。

使用自定义 CODEX_HOME

如果需要不同的配置 Profile（比如自动化用户），可以设置 CODEX_HOME 环境变量：

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

---

验证配置

# 从仓库根目录确认全局和项目文件都正确加载
codex --ask-for-approval never "Summarize the current instructions."

# 确认子目录 override 覆盖了上层规则
codex --cd subdir --ask-for-approval never "Show which instruction files are active."

如果需要审计 Codex 加载了哪些指令文件，查看 ~/.codex/log/codex-tui.log 或最近的 session-*.jsonl 文件。

指令看起来没更新？重启 Codex 在目标目录里即可——Codex 每次运行都会重新构建指令链，没有缓存需要清理。

---

常见问题排查

问题	排查方向
什么都没加载	确认你在正确的仓库目录，codex status 报告的 workspace root 是否正确；检查指令文件不是空的
出现了错误的指导	检查目录树更高层是否有 AGENTS.override.md，删除或重命名它回退到普通文件
Fallback 文件名没被识别	确认 project_doc_fallback_filenames 里没有拼写错误，重启 Codex
指令被截断	提高 project_doc_max_bytes 或把大文件拆分到子目录里
Profile 混乱	启动 Codex 前先运行 echo $CODEX_HOME，检查是否指向了非预期的目录

---

常见问题

Q: AGENTS.md 和 AGENTS.override.md 的区别是什么？

A: 两个文件名在语义上是一样的——都会被加载为指令文件。唯一的区别是：当同一目录下两个文件都存在时，Codex 只读 AGENTS.override.md，忽略 AGENTS.md。这让你可以创建临时 override 而不用修改原文件，删除 override 就自动回退。

Q: 多个 AGENTS.md 的优先级是怎么计算的？

A: 靠近当前工作目录的文件优先级更高（出现在组合 Prompt 的后面）。所以子目录里的规则会覆盖仓库根目录的规则，仓库规则又覆盖全局规则。

Q: AGENTS.md 写多长合适，会影响 token 用量吗？

A: 会。AGENTS.md 的内容会出现在每次对话的上下文里，内容越长 token 消耗越多。建议只写关键规则，把大量文档放到 references 目录里按需引用，而不是全部塞进 AGENTS.md。