English
主导航

推荐
API 仪表板

使用 AGENTS.md 自定义指令

为你的项目向 Codex 提供额外的指令和上下文

Codex 会读取 AGENTS.md 文件，然后再执行任何操作。通过将全局指导与特定项目的覆盖规则进行分层，无论你打开哪个代码仓库，每次启动任务时都能拥有一致的期望。

Codex 如何发现指导

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

  1. 全局范围： 在你的 Codex 主目录中（默认为 ~/.codex，除非你设置了 CODEX_HOME），Codex 会读取 AGENTS.override.md （如果存在）。否则，Codex 会读取 AGENTS.md。Codex 仅使用此层级中的第一个非空文件。
  2. 项目范围： 从项目根目录（通常是 Git 根目录）开始，Codex 会一直向下遍历到您当前的工作目录。如果 Codex 找不到项目根目录，它只会检查当前目录。在路径上的每个目录中，它会检查是否存在 AGENTS.override.md，然后 AGENTS.md，然后是中的任何回退名称 project_doc_fallback_filenames。Codex 每个目录最多包含一个文件。
  3. 合并顺序： Codex 会从根目录开始拼接文件，并用空行将它们连接起来。由于靠近当前目录的文件在合并后的提示词中出现得更晚，因此它们会覆盖先前的指引。

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

创建全局指导

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

  1. 确保目录存在：

    mkdir -p ~/.codex

  2. 创建 ~/.codex/AGENTS.md with reusable preferences:

    # ~/.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.

  3. 在任何位置运行 Codex 以确认其加载了该文件：

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

    预期结果：Codex 会引用来自 ~/.codex/AGENTS.md 的内容，然后再提出工作建议。

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

分层项目指令

仓库级别的文件能让 Codex 了解项目规范，同时依然继承您的全局默认设置。

  1. 在您的仓库根目录中，添加一个 AGENTS.md 涵盖基本设置的文件：

    # AGENTS.md

## Repository expectations

- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.

  2. 当特定团队需要不同规则时，在嵌套目录中添加覆盖配置。例如，在 services/payments/ 中创建 AGENTS.override.md:

    # 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.

  3. 从 payments 目录启动 Codex：

    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 支付服务规则
      • README.md
    • search/
      • AGENTS.md
      • …

自定义回退文件名

如果您的代码库已经使用了不同的文件名（例如 TEAM_GUIDE.md），请将其添加到回退列表中，以便 Codex 将其视为指令文件。

  1. 编辑您的 Codex 配置：

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

  2. 重启 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 directory.

验证您的设置

  • 在 Agent Builder 内部运行 codex --ask-for-approval never "Summarize the current instructions." 从代码库根目录运行。Codex 应按优先级顺序回显全局和项目文件中的指引。
  • 使用 codex --cd subdir --ask-for-approval never "Show which instruction files are active." 以确认嵌套的覆盖规则会替换更宽泛的规则。
  • 检查 ~/.codex/log/codex-tui.log （或者如果启用了会话日志，则为最新的 session-*.jsonl 文件），以便在需要审查 Codex 加载了哪些指令文件时进行审计。
  • 如果指令看起来已过时，请在目标目录中重启 Codex。Codex 会在每次运行时（以及在每次 TUI 会话开始时）重新构建指令链，因此无需手动清除缓存。

排查发现问题

  • 没有任何内容加载： 验证您是否在预期的代码库中，并且 codex status 报告了您预期的工作区根目录。确保指令文件包含内容；Codex 会忽略空文件。
  • 出现了错误的指引： 查找 AGENTS.override.md 在目录树更上层或 Codex 主目录下。重命名或移除覆盖文件以回退到常规文件。
  • Codex 会忽略回退文件名： 请确认你在 project_doc_fallback_filenames 中列出的名称没有拼写错误，然后重启 Codex 以使更新的配置生效。
  • 指令已截断： 提高 project_doc_max_bytes 或将大文件拆分到嵌套目录中，以保持关键指导内容完整。
  • 配置文件混淆： 在 Agent Builder 内部运行 echo $CODEX_HOME 然后再启动 Codex。非默认值会将 Codex 指向与你编辑过的目录不同的主目录。

后续步骤

  • 访问官方 AGENTS.md 网站了解更多信息。
  • 审查 提示 Codex 适用于与持久性指导配合良好的对话模式。