OpenAI Codex 会在运行前读取 AGENTS.md 作为持续指令，适合给全局默认规则、仓库规则和子目录覆盖规则分层配置。按全局目录、项目根到当前目录的顺序合并，离当前工作目录越近的文件优先级越高；需要兼容别名文件时，配置 project_doc_fallback_filenames，遇到内容过长时提高 project_doc_max_bytes 或拆分到更深目录。
OpenAI Codex AGENTS.md 配置与读取
OpenAI Codex 会先读取 AGENTS.md，再开始执行任务。你可以用它给整个团队、某个仓库、某个子目录设置固定工作约定，让每次运行都遵守相同规则。
Codex 怎么发现 AGENTS.md
Codex 在启动时会构建一条指令链，TUI 场景下一般是每次启动会话时构建一次。它按下面的优先级查找：
- 全局范围：在 Codex home 目录中，默认是
~/.codex，除非你设置了CODEX_HOME。Codex 先读AGENTS.override.md，如果不存在再读AGENTS.md，这一层只使用第一个非空文件。 - 项目范围：从项目根目录开始，通常是 Git root，一直向下走到当前工作目录。如果找不到项目根，只检查当前目录。路径上的每个目录都会依次检查
AGENTS.override.md、AGENTS.md，以及project_doc_fallback_filenames里配置的备用文件名。每个目录最多纳入一个文件。 - 合并顺序：Codex 会从根目录一路向下把文件拼接起来，中间用空行分隔。越接近当前目录的文件越晚出现，因此会覆盖更早的指令。
Codex 会跳过空文件，并在合并内容达到 project_doc_max_bytes 的限制后停止继续加入文件。默认上限是 32 KiB。关于这些配置项的细节，见 Project instructions discovery。如果触顶，可以提高限制，或者把指令拆到更深层的目录里。
怎么创建全局 AGENTS.md
把通用默认规则放到 Codex home 目录里，这样每个代码库都会继承。
-
确保目录存在：
mkdir -p ~/.codex -
创建
~/.codex/AGENTS.md，写入可复用的偏好：# ~/.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。删除 override 后，会恢复共享规则。
怎么叠加项目级指令
仓库级文件可以让 Codex 了解当前项目的规范，同时继续继承全局默认值。
-
在仓库根目录添加
AGENTS.md，写入基础设置：# AGENTS.md ## Repository expectations - Run `npm run lint` before opening a pull request. - Document public utilities in `docs/` when you change behavior. -
如果某些团队需要不同规则，可以在更深的目录里添加 override。比如在
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. -
从 payments 目录启动 Codex：
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."预期结果：Codex 会先报告全局文件，再报告仓库根目录的
AGENTS.md，最后报告 payments 的 override。
Codex 会在到达当前目录时停止继续向下搜索，所以越专门的规则，越应该放在离工作目录更近的位置。
备用文件名怎么配置
如果你的仓库已经在用别的文件名，比如 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 会把这些替代文件当作指令：
示例目录结构会变成：
TEAM_GUIDE.md：通过备用列表识别.agents.md：仓库根目录的备用文件support/AGENTS.override.md：覆盖备用规则playbooks/：继续向下查找其下的指令文件
怎么设置不同的 CODEX_HOME
当你想切换到另一个 profile，例如项目专用的自动化用户，可以设置 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."验证更深层的 override 是否会替换更宽泛的规则。 - 会话结束后，如果需要审计 Codex 读了哪些文件，可以查看
~/.codex/log/codex-tui.log；如果启用了 session logging，也可以看最近的session-*.jsonl。 - 如果感觉指令还是旧的，重启目标目录里的 Codex。Codex 每次运行都会重建指令链，TUI 也会在每次会话开始时重建，所以没有可手动清理的缓存。
AGENTS.md 不生效怎么排查
- 什么都没加载：确认你在目标仓库里，并且
codex status报告的 workspace root 符合预期。还要检查指令文件是否有内容，Codex 会忽略空文件。 - 出现了错误的规则：检查目录树上方，或者 Codex home 下，是否存在更高优先级的
AGENTS.override.md。重命名或删除 override 后，会回退到普通文件。 - Codex 忽略备用文件名：确认你在
project_doc_fallback_filenames里写的名字没有拼写错误，然后重启 Codex 让新配置生效。 - 指令被截断：提高
project_doc_max_bytes，或者把大文件拆到更深的目录里，保住关键规则。 - profile 混淆：启动 Codex 前先运行
echo $CODEX_HOME。如果不是默认值，Codex 读到的会是另一个 home 目录，不一定是你刚改过的那个。
常见问题
OpenAI Codex 怎么让 AGENTS.md 生效
把 AGENTS.md 放到 Codex home、仓库根目录或当前工作目录路径上，Codex 启动时会自动读取。全局文件先合并，越靠近当前目录的项目文件优先级越高。
Codex 为什么读不到我写的 TEAM_GUIDE.md
TEAM_GUIDE.md 这类文件不会默认参与发现，只有把它加入 project_doc_fallback_filenames 后，Codex 才会把它当作指令文件。改完配置后需要重启 Codex。
OpenAI Codex 指令为什么会被截断
合并后的内容超过 project_doc_max_bytes 时，Codex 会停止继续添加文件。可以提高这个上限，或者把规则拆分到更深的子目录里。