使用 AGENTS.md 自定义指令

身份非官方简体中文镜像

翻译状态 AI 翻译 / AI 审校

来源版本官方未提供

同步日期 2026-07-26

官方原文 learn.chatgpt.com

Codex 在执行任何工作前都会读取 AGENTS.md 文件。通过将全局指导与项目特定的覆盖规则分层组合，无论打开哪个代码仓库，都可以让每项任务从一致的预期开始。

Codex 如何发现指导

Codex 启动时会构建指令链（每次运行一次；在 TUI 中通常意味着每次启动会话一次）。发现过程遵循以下优先级顺序：

**全局范围：**在 Codex 主目录中（默认为 ~/.codex，除非设置了 CODEX_HOME），Codex 会读取 AGENTS.override.md（如果存在）。否则，Codex 会读取 AGENTS.md。在此级别，Codex 只使用第一个非空文件。
**项目范围：**Codex 从项目根目录（通常是 Git 根目录）开始，向下遍历到当前工作目录。如果 Codex 找不到项目根目录，则只检查当前目录。在路径上的每个目录中，Codex 依次检查 AGENTS.override.md、AGENTS.md，然后检查 project_doc_fallback_filenames 中的备用名称。每个目录最多包含一个文件。
**合并顺序：**Codex 从根目录向下拼接文件，并使用空行连接。距离当前目录更近的文件会覆盖较早的指导，因为它们在组合提示词中出现得更晚。

Codex 会跳过空文件，并在组合大小达到 project_doc_max_bytes 定义的上限（默认为 32 KiB）后停止添加文件。有关这些配置项的详细信息，请参阅项目指令发现。达到上限时，可以提高限制，或将指令拆分到嵌套目录中。

创建全局指导

在 Codex 主目录中创建持久化默认设置，使每个代码仓库都能继承你的工作约定。

确保目录存在：
Terminal window
```
mkdir -p ~/.codex
```

创建包含可复用偏好的 ~/.codex/AGENTS.md：

## 工作约定

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

在任意位置运行 Codex，确认它加载了该文件：
Terminal window
```
codex --ask-for-approval never "Summarize the current instructions."
```
预期结果：Codex 在提出工作方案前，会引用 ~/.codex/AGENTS.md 中的各项内容。

当需要临时覆盖全局设置而不删除基础文件时，请使用 ~/.codex/AGENTS.override.md。删除覆盖文件即可恢复共享指导。

分层设置项目指令

代码仓库级文件可以让 Codex 了解项目规范，同时继续继承你的全局默认设置。

在代码仓库根目录中添加涵盖基本设置的 AGENTS.md：

## 代码仓库要求

- 创建拉取请求前运行 `npm run lint`。
- 修改行为时，在 `docs/` 中记录公共工具函数。

当特定团队需要不同规则时，在嵌套目录中添加覆盖文件。例如，在 services/payments/ 中创建 AGENTS.override.md：
services/payments/AGENTS.override.md
```
## Payments 服务规则

- 使用 `make test-payments` 代替 `npm test`。
- 未通知安全频道前，绝不轮换 API 密钥。
```
从 payments 目录启动 Codex：
Terminal window
```
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
```
预期结果：Codex 依次报告全局文件、代码仓库根目录中的 AGENTS.md，以及最后的 payments 覆盖文件。

Codex 到达当前目录后会停止搜索，因此应尽可能将覆盖文件放在靠近专门工作的位置。

以下是添加全局文件和 payments 专用覆盖文件后的代码仓库示例：

├── AGENTS.md                         # 代码仓库要求
└── services/
    ├── payments/
    │   ├── AGENTS.md                 # 因存在覆盖文件而忽略
    │   ├── AGENTS.override.md        # Payments 服务规则
    │   └── README.md
    └── search/
        ├── AGENTS.md
        └── …                         # 占位符

添加代码审查规则

对于 GitHub 中的 Codex 代码审查，请在最接近规则所适用代码的 AGENTS.md 中添加 ## Code Review Rules 部分。将整个代码仓库范围的检查放在根目录中，将特定服务的检查放在嵌套文件中。

## Code Review Rules
### Experiment cohorts
- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

规则应简明扼要，说明需要标记的行为，以及安全路径或例外情况，并将格式检查和 lint 检查交由 CI 处理。有关设置和编写规则的指导，请参阅自定义 Codex 的审查内容。

自定义备用文件名

如果代码仓库已经使用其他文件名（例如 TEAM_GUIDE.md），请将其添加到备用列表中，以便 Codex 将其视为指令文件。

编辑 Codex 配置：

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 会将这些替代文件视为指令：

├── TEAM_GUIDE.md                    # 通过备用列表检测到
├── .agents.md                       # 根目录中的备用文件
└── support/
    ├── AGENTS.override.md           # 覆盖备用指导
    └── playbooks/
        └── …                        # 占位符

当需要使用不同的配置档案（例如项目专用的自动化用户）时，请设置 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 加载了哪些指令文件，请选择启用纯文本 TUI 日志：运行 codex -c log_dir=./.codex-log，然后检查 ./.codex-log/codex-tui.log；如果启用了会话日志记录，也可以检查最新的 session-*.jsonl 文件。
如果指令看起来过时，请在目标目录中重启 Codex。Codex 会在每次运行时（以及每次 TUI 会话开始时）重建指令链，因此无需手动清除缓存。

排查发现问题

**没有加载任何内容：**确认你位于预期的代码仓库中，并且 codex status 报告的工作区根目录正确。确保指令文件包含内容；Codex 会忽略空文件。
**出现了错误的指导：**检查目录树上层或 Codex 主目录中是否存在 AGENTS.override.md。重命名或移除覆盖文件，即可回退到常规文件。
**Codex 忽略备用名称：**确认已在 project_doc_fallback_filenames 中列出这些名称且没有拼写错误，然后重启 Codex，使更新后的配置生效。
**指令被截断：**提高 project_doc_max_bytes，或将大型文件拆分到嵌套目录中，以保留关键指导。
**配置档案混淆：**启动 Codex 前运行 echo $CODEX_HOME。非默认值表示 Codex 指向了不同于你编辑的主目录。

后续步骤

访问官方 AGENTS.md 网站，了解更多信息。
查看提示 Codex，了解适合搭配持久化指导的对话模式。