Codex AGENTS.md | 全局说明与项目覆盖 - Codex 实践教程

Codex 会在开始任何工作前读取 AGENTS.md 文件。通过把全局指导和项目级覆盖层叠起来，你就能在每次打开任意仓库时，都从一致的工作预期开始。

Codex 如何发现这些指导

Codex 启动时会整理出一条本次运行要使用的指令链。这个过程每次运行都会重新执行；在终端界面（TUI）中，通常就是每次新建会话时重新构建。查找顺序如下：

全局层：先检查 Codex 主目录（默认是 ~/.codex，也可以通过 CODEX_HOME 指定）。如果存在 AGENTS.override.md，就使用它；否则再读取 AGENTS.md。这一层只会采用找到的第一个非空文件。
项目层：然后从项目根目录（通常是 Git 根目录）一路检查到当前工作目录。如果没有找到项目根，就只检查当前目录。沿途每一级目录都会按 AGENTS.override.md、AGENTS.md、project_doc_fallback_filenames 中定义的备用文件名这一顺序查找；每个目录最多只会纳入一个文件。
合并顺序：最后，Codex 会按“从根到当前目录”的顺序把这些文件拼接起来。越靠近当前目录的文件越靠后，因此会覆盖前面更通用的说明。

空文件会被跳过。合并后的总大小一旦达到 project_doc_max_bytes 设定的上限（默认 32 KiB），Codex 就不会再继续加入更多文件。关于这些参数，参见项目指令发现。如果触到上限，可以调大限制，或把指令拆到更深一层的目录中。

在 Codex 主目录中创建持久默认值，这样每个仓库都会继承你的工作约定。

确保目录存在：

mkdir -p ~/.codex

创建 ~/.codex/AGENTS.md，写入可复用偏好：

# ~/.codex/AGENTS.md

## 工作约定

- 修改 JavaScript 文件后，始终运行 `npm test`。
- 安装依赖时优先使用 `pnpm`。
- 添加新的生产依赖前先征求确认。

在任意目录运行 Codex，确认它已加载该文件：

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

预期结果：Codex 会在给出工作建议前，先引用 ~/.codex/AGENTS.md 中的条目。

当你需要临时性的全局覆盖，而又不想删除基础文件时，可以使用 ~/.codex/AGENTS.override.md。删除这个覆盖文件后，就会恢复共享指导。

仓库级文件可以让 Codex 感知项目规范，同时继续继承你的全局默认值。

在仓库根目录添加一个 AGENTS.md，写入基础约定：

# AGENTS.md

## 仓库通用约定

- 在创建 pull request 前运行 `npm run lint`。
- 修改行为时，在 `docs/` 中记录对外公共工具的变化。

当某些团队需要不同规则时，在嵌套目录中添加覆盖文件。例如在 services/payments/ 下创建 AGENTS.override.md：

# services/payments/AGENTS.override.md

## payments 服务规则

- 使用 `make test-payments`，不要使用 `npm test`。
- 轮换 API key 前，必须先通知安全频道。

从 payments 目录启动 Codex：

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

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

Codex 的搜索会在到达当前目录时停止，因此应把覆盖文件尽量放在靠近专门化工作的地方。

添加全局文件和 payments 专属覆盖文件后，仓库结构示例如下：

如果你的仓库已经在使用其他文件名（例如 TEAM_GUIDE.md），你可以把它加入备用列表，让 Codex 也把它当作说明文件。

编辑你的 Codex 配置：

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

重启 Codex，或者运行一条新的命令，让更新后的配置被加载。

这样一来，Codex 就会按以下顺序检查每个目录：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。不在这个列表中的文件名不会参与说明文件发现。更大的字节上限则允许合并更多指导内容后再截断。

设置好备用列表后，Codex 会把这些替代文件也视作说明文件：

如果你希望使用不同配置档，例如某个项目专用的自动化账号，可以设置 CODEX_HOME 环境变量：

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

预期结果：输出会列出相对于自定义 .codex 目录的文件路径。

在仓库根目录运行 codex --ask-for-approval never "Summarize the current instructions."。正常情况下，Codex 会按优先级复述全局和项目级指导。
使用 codex --cd subdir --ask-for-approval never "Show which instruction files are active."，确认嵌套目录中的覆盖文件是否成功覆盖了更上层规则。
如果你需要审计 Codex 实际加载了哪些说明文件，可以用 codex -c log_dir=./.codex-log 启用明文 TUI 日志并查看 ./.codex-log/codex-tui.log，或者在开启会话日志时检查最近的 session-*.jsonl。
如果说明看起来像是旧的，请在目标目录里重启 Codex。Codex 会在每次运行时重新构建指令链，在 TUI 中则是在每次会话开始时重建，所以没有需要手工清理的缓存。