使用 AGENTS.md 自定义指令
如需完整文档索引，请参阅 llms.txt。文档页面的 Markdown 版本可通过在页面后追加
.md来获取 URL。
Codex 在执行任何工作前都会读取 AGENTS.md 文件。通过将全局指导与项目特定的覆盖规则分层组合，无论打开哪个代码仓库，都可以让每项任务从一致的预期开始。
Codex 如何发现指导文件
Section titled “Codex 如何发现指导文件”Codex 启动时会构建指令链（每次运行一次；在 TUI 中通常意味着每次启动会话一次）。发现过程遵循以下优先级顺序：
- 全局范围： 在你的 Codex 主目录中（默认为
~/.codex，除非你设置了CODEX_HOME）， Codex 会读取AGENTS.override.md（如果存在）。否则， Codex 会读取AGENTS.md。 Codex 在此级别仅使用第一个非空文件。 - 项目范围： 从项目根目录（通常是 Git 根目录）开始， Codex 会一路向下遍历到你当前的工作目录。如果 Codex 找不到项目根目录，它只会检查当前目录。在路径上的每个目录中，它会依次检查
AGENTS.override.md，然后AGENTS.md，然后是project_doc_fallback_filenames中的任何备用名称。 Codex 每个目录最多包含一个文件。 - 合并顺序： Codex 会从根目录向下拼接文件，并用空行连接它们。离你当前目录更近的文件会覆盖较早的指导，因为它们在合并后的提示中出现得更晚。
Codex 会跳过空文件，并在组合大小达到 project_doc_max_bytes 定义的上限（默认为 32 KiB）后停止添加文件。有关这些配置项的详细信息，请参阅项目指令发现。达到上限时，可以提高限制，或将指令拆分到嵌套目录中。
创建全局指导
Section titled “创建全局指导”在 Codex 主目录中创建持久化默认设置，使每个代码仓库都能继承你的工作约定。
- 确保目录存在：
mkdir -p ~/.codex- 创建
~/.codex/AGENTS.md并写入可复用的偏好设置：
## Working agreements
- Always run `npm test` after modifying JavaScript files. - Prefer `pnpm` when installing dependencies. - Ask for confirmation before adding new production dependencies.- 在任意位置运行 Codex 以确认它加载了该文件：
codex --ask-for-approval never "Summarize the current instructions."预期： Codex 会先引用 ~/.codex/AGENTS.md 中的条目，然后再提出工作建议。
当需要临时覆盖全局设置而不删除基础文件时，请使用 ~/.codex/AGENTS.override.md。删除覆盖文件即可恢复共享指导。
分层设置项目指令
Section titled “分层设置项目指令”代码仓库级文件可以让 Codex 了解项目规范，同时继续继承你的全局默认设置。
- 在你的仓库根目录中，添加一个
AGENTS.md来覆盖基本设置：
## Repository expectations
- Run `npm run lint` before opening a pull request. - Document public utilities in `docs/` when you change behavior.- 当特定团队需要不同规则时，在嵌套目录中添加覆盖。例如，在
services/payments/内创建AGENTS.override.md：
## Payments service rules
- Use `make test-payments` instead of `npm test`. - Never rotate API keys without notifying the security channel.- 从 payments 目录启动 Codex ：
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."预期： Codex 会先报告全局文件，其次是仓库根目录的 AGENTS.md ，最后是 payments 覆盖。
Codex 到达当前目录后会停止搜索，因此应尽可能将覆盖文件放在靠近专门工作的位置。
以下是添加全局文件和 payments 专用覆盖文件后的代码仓库示例：
交互内容： FileTree 的动态演示请参阅页面顶部的官方原文链接。
添加代码审查规则
Section titled “添加代码审查规则”对于 Codex 中的 GitHub代码审查，
请在离 ## Code Review Rules 规则所管辖代码最近的 AGENTS.md 中添加一个
部分。将仓库范围的检查放在根目录，并将服务特定的
检查放在嵌套文件中。
## 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 审查的内容 以获取 设置和规则编写指导。
自定义备用文件名
Section titled “自定义备用文件名”如果代码仓库已经使用其他文件名（例如 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 会将这些替代文件视为指令：
交互内容： FileTree 的动态演示请参阅页面顶部的官方原文链接。
当需要使用不同的配置档案（例如项目专用的自动化用户）时，请设置 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 会话开始时）重建指令链，因此无需手动清除缓存。
排查发现问题
Section titled “排查发现问题”- 未加载任何内容： 确认你位于预期的仓库中，并且
codex status报告的是你期望的工作区根目录。确保指令文件包含内容； Codex 会忽略空文件。 - 出现了错误的指导： 查找目录树更高层级中或你的
AGENTS.override.md主目录下的 Codex 。重命名或移除该覆盖，以回退到常规文件。 - Codex 忽略备用名称： 确认你在
project_doc_fallback_filenames中列出的名称没有拼写错误，然后重启 Codex 使更新后的配置生效。 - 指令被截断： 提高
project_doc_max_bytes，或将大型文件拆分到嵌套目录中，以保留关键指导的完整性。 - 配置档混淆： 在启动
echo $CODEX_HOME之前运行 Codex。非默认值会将 Codex 指向与你编辑的目录不同的主目录。