2026 Codex AGENTS.md 教程：全局配置、目录覆盖与最佳实践

先看结论：全局写习惯，仓库写事实，子目录写例外

最稳妥的结构是三层：个人长期偏好放全局文件，整个仓库共同遵守的命令与边界放根目录，只有某个子项目需要的差异再放到子目录。

~/.codex/AGENTS.md                 # 个人全局指令
project/AGENTS.md                  # 整个仓库的共同规则
project/apps/web/AGENTS.md         # web 子项目的补充或覆盖
project/apps/api/AGENTS.override.md # api 目录临时或强制覆盖

Codex 启动一次运行时会建立一条指令链。项目范围通常从仓库根目录开始，一直检查到当前工作目录；越靠近当前目录的说明越晚加入，因此在发生冲突时更具体的下层规则占优。它不是把父文件整份删除，而是按顺序合并后由后面的具体说明覆盖冲突。

AGENTS.md、config.toml、Skill 和 Rules 不是同一件事

最常见的错误是把所有内容塞进一个文件：在 AGENTS.md 里粘贴 Token 和完整客户端配置，或在 Rules 里写产品需求。职责分开后更容易审查，也能减少某条说明被错误地应用到所有任务。

如果要封装“生成迁移文件并验证数据库”的专用流程，更适合创建 Codex Skill；如果是 MCP Server、OAuth 或工具范围，进入 Codex MCP 配置教程；如果配置文件无法加载，进入 config.toml 排查。

Codex 如何发现 AGENTS.md：顺序比文件数量更重要

OpenAI 当前规则可以拆成两个阶段：先读取 Codex home 中的全局指令，再从项目根目录走到当前工作目录。每一级目录最多选择一个非空文件，最后把选中的内容从上到下合并。

空文件会被跳过；同一目录不会同时加载 AGENTS.override.md 和 AGENTS.md。如果找不到项目根，Codex 只检查当前目录的项目说明。由此带来两个实践结论：

• 不要在同一目录维护两份都期待生效的规则文件；override 存在且非空时，普通文件不会同时加入。
• 不要把子项目专用命令写进仓库根目录，否则从其他目录启动的任务也会看到它。
• 从不同工作目录启动 Codex，最终指令链可能不同；排查时必须记录当前目录。
• 编辑文件后若当前运行没有反映变化，开启一次新的运行再验证发现结果。

全局 AGENTS.md 放在哪里，应该写什么

默认 Codex home 通常是 ~/.codex，因此个人全局文件可放在：

~/.codex/AGENTS.md

如果设置了 CODEX_HOME，应以该目录为准，而不是继续假定 ~/.codex。本机、WSL、SSH、Dev Container 与另一台电脑也可能各有不同的 home，所以“我已经写过全局文件”不代表当前 host 一定能看到。

全局文件适合稳定且跨项目成立的个人规则，例如：

# Personal defaults

- 回答和提交信息使用简体中文。
- 修改前先阅读仓库已有说明，不覆盖未提交的用户改动。
- 搜索文件优先使用 rg；不可用时再选择替代工具。
- 完成代码修改后，运行与改动范围匹配的测试。
- 不在输出、日志、提交或截图中暴露密钥和用户数据。

不要在全局文件强制所有项目使用同一个包管理器、测试命令或框架约定。跨项目并不成立的内容应该移到对应仓库。也不要把 API Key、Cookie、Session、私有 URL 或客户数据写进全局指令。

仓库根目录与子目录如何分层

根目录文件是项目的共同入口，应该帮助第一次进入仓库的人快速回答：项目是什么、主要目录在哪里、用什么命令验证、哪些文件不能随意修改、完成标准是什么。

shop-platform/
├── AGENTS.md
├── package.json
├── apps/
│   ├── web/
│   │   ├── AGENTS.md
│   │   └── src/
│   └── api/
│       ├── AGENTS.md
│       └── src/
└── packages/
    └── ui/
        └── AGENTS.md

从 apps/web 启动任务时，Codex 会把根目录说明与 web 目录说明按顺序组合；它不会读取相邻的 apps/api/AGENTS.md。因此可以让根目录负责全仓库边界，让每个应用写自己的命令和局部约定。

AGENTS.override.md、fallback 文件名与 32 KiB 限制

什么时候使用 AGENTS.override.md

override 适合明确替换同一目录普通文件的场景，例如迁移期间暂停某类生成操作，或在个人全局层临时改变默认行为。由于同一目录只选一个文件，创建 override 后要把当前仍需执行的关键规则一并写入，并在完成后删除或回收。

什么时候配置 fallback 文件名

有些仓库已经使用 CONTRIBUTING_AGENT.md 或团队自定义文件名。Codex 可以通过 project_doc_fallback_filenames 把这些名称加入候选；它们排在 override 与标准 AGENTS.md 之后，只在前面的候选没有产生非空内容时使用。

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CONTRIBUTING_AGENT.md", ".agents.md"]

fallback 是兼容现有仓库命名的办法，不是让同一目录同时拼接更多文件。多个文档需要分别生效时，应按目录层级拆分，或把具体背景放入普通文档后在 AGENTS.md 中指明何时读取。

合并内容默认最多 32 KiB

OpenAI 当前文档说明，项目指令链达到 project_doc_max_bytes 后会停止继续加入，默认上限是 32 KiB。超出时不要第一反应就是无限提高数值：先删除重复解释，把大段设计背景移到独立文档，并在对应任务需要时引用；确实需要时才在 config.toml 调整上限。

# ~/.codex/config.toml
project_doc_max_bytes = 65536

提高上限会增加每次运行注入的上下文，也可能让关键规则更难被识别。短、明确、靠近适用目录的说明通常比一份数千行总手册更有效。

一份可以直接改写的项目 AGENTS.md 模板

在 Codex CLI 的当前目录输入 /init 可以生成一份起始模板。它适合快速开始，但生成后仍要对照仓库的真实脚本、CI 和目录结构逐条修改，不能把初稿直接当成团队规范。

# Project instructions

## Scope
- 本文件适用于整个仓库。
- apps/web 与 apps/api 的额外规则见各自目录中的 AGENTS.md。

## Project map
- apps/web: 用户端 Web 应用。
- apps/api: HTTP API 与后台任务。
- packages/ui: 共享 UI 组件；修改公开接口要同步更新使用方。

## Setup and commands
- 使用仓库现有包管理器和锁文件，不切换工具。
- 安装：pnpm install --frozen-lockfile
- 单元测试：pnpm test
- 类型检查：pnpm typecheck
- 生产构建：pnpm build

## Change rules
- 修改前检查工作树并保留无关的未提交改动。
- 不手改生成文件；通过项目脚本重新生成。
- 数据库 schema 变化必须附带迁移和回滚说明。
- 不把密钥、Cookie、Session 或真实用户数据写入代码和日志。

## Definition of done
- 运行与改动范围匹配的测试，并报告未运行的检查。
- 用户可见行为变化要更新对应文档。
- 提交只包含当前任务相关文件。

模板中的命令只是结构示例，不能不核对就复制。先从仓库的 package scripts、Makefile、CI、贡献文档和实际目录中验证命令，再写入 AGENTS.md。错误但语气很确定的指令比没有指令更危险。

AGENTS.md 怎么写更有效：把愿望改成可检查的动作

1. 先写真实约束

   从 CI、构建脚本、目录结构和团队复盘中提取，不根据理想架构杜撰。

2. 使用命令和路径

   告诉 Codex 在哪里查、运行什么、成功结果是什么。

3. 说明作用域

   规则只针对当前目录时明确写出，不把例外扩大到整个仓库。

4. 保留理由但控制长度

   高风险或反直觉规则说明一句原因，避免每条都变成长篇背景。

5. 定期删除失效内容

   依赖、命令、目录和组织流程变化后同步更新；过期指令会持续误导。

如何验证 Codex 实际读到了哪一份指令

1. 记录当前 host 与工作目录

   明确是在 macOS、Windows、WSL、SSH 还是容器，以及 Codex 从哪个目录开始工作。

2. 列出从根到当前目录的候选文件

   检查每级是否存在 override、标准文件或 fallback 文件，是否为空。

3. 核对 CODEX_HOME

   不要假定全局文件一定在 ~/.codex；环境变量可能改变位置。

4. 开启新运行做低风险测试

   让 Codex 复述当前仓库的构建命令和禁止修改目录，确认答案来自预期文件。

5. 制造一个可撤销的目录差异

   在测试分支的子目录加入一条明确说明，比较从根目录和子目录启动时的结果。

6. 检查总大小

   规则缺失时统计合并内容是否接近默认 32 KiB，并删除重复或下沉到正确目录。

常见的不生效原因

• 文件名大小写或扩展名错误，例如保存成 AGENTS.md.txt。
• 当前 host 的 CODEX_HOME 与你编辑的位置不同。
• 同一目录存在非空 AGENTS.override.md，因此普通文件未被选中。
• 从另一个工作目录启动，目标子目录不在发现路径上。
• 文件为空，或总内容触及 project_doc_max_bytes。
• 把 config.toml、Rules 或 Skill 的职责误当成 AGENTS.md 的加载问题。
• 仍在旧运行中验证刚修改的指令，没有重新开始一次运行。

团队仓库中的安全与评审边界

仓库级 AGENTS.md 会影响进入该目录的自动化工作，应像代码和 CI 配置一样评审。它可以提高一致性，也可能通过隐藏命令、宽泛授权或不安全的依赖安装扩大风险。需要周期运行时，先看 Codex Automations 定时任务、Worktree 与权限教程。

• 任何要求执行脚本、下载二进制或访问外部服务的修改都要核对来源。
• 不要在指令里要求关闭 Sandbox、跳过审批、绕过安全检查或自动批准所有工具。
• 敏感信息只写“从哪个受控环境变量读取”，不要写真实值。
• 第三方 Pull Request 修改 AGENTS.md 时单独审查，确认作用域和命令没有被悄悄扩大。
• 自动生成代码、数据库迁移、发布、付款和删除操作应保留人工确认或明确的受控流程。
• 为临时 override 写明原因、负责人和清理条件，避免永久覆盖正式规则。

AGENTS.md 不能提升套餐额度，也不能修复网络、登录、MCP 握手或文件系统权限。遇到 permission denied 应进入 Sandbox 权限排查；遇到用量限制应进入 Codex 额度专题。

Codex AGENTS.md 配置常见问题

Codex AGENTS.md 是什么？

它是 Codex 的项目自定义指令文件，用来提供构建、测试、架构、目录边界和交付要求。Codex 会按全局与项目目录层级发现并合并内容。

Codex AGENTS.md 应该放在哪里？

个人全局文件默认可放在 ~/.codex/AGENTS.md；仓库共同规则放项目根目录；子项目差异放对应子目录。设置了 CODEX_HOME 时，全局位置随之改变。

全局 AGENTS.md 怎么配置？

在 Codex home 中创建非空 AGENTS.md。若同目录存在非空 AGENTS.override.md，Codex 会优先选择 override，而不是同时加载普通文件。

多个 AGENTS.md 会互相覆盖吗？

会按从项目根到当前工作目录的顺序合并。更靠近当前目录的内容加入得更晚，因此冲突时更具体的下层说明占优；父层未冲突的内容仍然保留。

AGENTS.override.md 有什么用？

它在同一目录优先于普通 AGENTS.md，适合临时或强制替换该层说明。因为同一目录最多选择一个文件，override 应包含当前仍需保留的关键规则。

AGENTS.md 最大能写多大？

当前官方文档列出的项目指令合并默认上限是 32 KiB，由 project_doc_max_bytes 控制。优先去重和按目录拆分，确有需要时再调整。

Codex AGENTS.md 怎么写？

优先写真实命令、路径、禁止范围和可验证的完成标准。把“注意质量、遵守规范”等抽象要求改成具体动作，并删除与当前仓库不符的模板内容。

Codex 可以自动生成 AGENTS.md 吗？

可以在 Codex CLI 当前目录使用 /init 生成起始模板。生成后仍要按仓库实际命令、目录和评审要求修改，并由团队审查后再提交。

AGENTS.md 和 Codex Rules 有什么区别？

AGENTS.md 负责项目说明与工作约定；Codex Rules 负责 Sandbox 外部命令的允许、提示或禁止。两者解决不同层面的问题，不能互相替代。

AGENTS.md 和 Skill 有什么区别？

AGENTS.md 是进入某个代码范围时持续适用的项目指令；Skill 是按具体任务选择的可复用工作流，可以带脚本、模板和参考资料。

修改 AGENTS.md 后为什么没有生效？

检查 host、工作目录、CODEX_HOME、override、fallback、空文件和大小上限。当前运行可能已构建指令链，修改后应开启一次新运行再验证。