Codex 文档

Appearance

用 AGENTS.md 自定义指令 ​

Codex 在执行任务前会读取 AGENTS.md 文件。通过分层设置全局指导和项目级覆盖，每次打开项目时 Codex 都能带着一致的预期开始工作。

Codex 如何发现指令 ​

Codex 在启动时构建指令链（每次运行一次）。发现顺序如下：

  1. 全局范围：在 Codex 主目录（默认 ~/.codex）中，Codex 先查找 AGENTS.override.md，如果不存在则读取 AGENTS.md。
  2. 项目范围：从项目根目录（通常是 Git 根目录）向下遍历到当前工作目录。在每个目录中检查 AGENTS.override.md，然后 AGENTS.md。每个目录最多包含一个文件。
  3. 合并顺序：Codex 从根目录向下拼接文件，用空行分隔。更靠近当前目录的文件出现在组合提示的后面，因此优先级更高。

Codex 跳过空文件，并在合并大小达到限制（默认 32 KiB）时停止添加文件。

创建全局指导 ​

在 Codex 主目录中创建持久化默认值：

bash
mkdir -p ~/.codex

创建 ~/.codex/AGENTS.md：

markdown
# ~/.codex/AGENTS.md

## 工作约定

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

分层项目指令 ​

仓库级别的文件让 Codex 了解项目规范，同时仍继承全局默认值。

在仓库根目录添加 AGENTS.md：

markdown
# AGENTS.md

## 仓库要求

- 在打开 Pull Request 之前运行 `npm run lint`
- 更改行为时在 `docs/` 中更新公共工具文档

在嵌套目录中添加覆盖规则。例如在 services/payments/ 中创建 AGENTS.override.md：

markdown
# services/payments/AGENTS.override.md

## 支付服务规则

- 使用 `make test-payments` 而不是 `npm test`
- 轮换 API Key 时必须通知安全频道

Codex 到达当前目录后停止搜索，因此将覆盖文件放在尽可能靠近专业化工作的地方。

自定义后备文件名 ​

如果你的仓库使用不同的文件名（例如 TEAM_GUIDE.md），将其添加到后备列表中：

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

现在 Codex 在每个目录中按以下顺序检查：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。

验证设置 ​

bash
# 检查当前加载的指令
codex --ask-for-approval never "总结当前的指令。"

# 从子目录确认嵌套覆盖
codex --cd subdir --ask-for-approval never "显示哪些指令文件处于活动状态。"

由 Codex 构建

Copyright 2025 OpenAI