C codex实践指南网 RSS

Configuration

AGENTS.md

AGENTS.md 是仓库级持久说明，适合写构建、测试、风格和发布约束。

返回文档目录

Codex 会在开始任何工作之前读取 AGENTS.md 文件。通过把全局 guidance 与项目专属 overrides 分层组合，无论打开哪个 repository，你都可以让每个任务从一致的预期开始。

Codex 如何发现 guidance

Codex 启动时会构建 instruction chain（每次运行一次；在 TUI 中通常表示每次启动 session 一次）。Discovery 遵循以下优先级顺序：

Global scope：在你的 Codex home directory 中（默认是 ~/.codex，除非设置了 CODEX_HOME），如果存在 AGENTS.override.md，Codex 会读取它；否则读取 AGENTS.md。Codex 在这一层级只使用第一个非空文件。

Project scope：从 project root（通常是 Git root）开始，Codex 会一路向下检查到当前 working directory。如果 Codex 找不到 project root，则只检查当前目录。在路径上的每个目录中，它依次检查 AGENTS.override.md、AGENTS.md，以及 project_doc_fallback_filenames 中的 fallback names。每个目录最多只包含一个文件。

Merge order：Codex 会从 root 向下拼接文件，并用空行连接。更接近当前目录的文件会覆盖较早的 guidance，因为它们在合并后的 prompt 中出现得更靠后。

Codex 会跳过空文件，并在合并后的大小达到 project_doc_max_bytes 定义的限制时停止继续添加文件（默认 32 KiB）。有关这些 knobs 的详情，请参阅 Project instructions discovery 。达到上限时，可以提高限制，或把 instructions 拆分到嵌套目录中。

创建全局 guidance

在你的 Codex home directory 中创建持久默认值，让每个 repository 都继承你的工作约定。

确认目录存在： 

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 中的项目。

当你需要临时的全局 override，但又不想删除基础文件时，可以使用 ~/.codex/AGENTS.override.md。删除该 override 即可恢复共享 guidance。

分层放置项目 instructions

Repository-level 文件让 Codex 了解项目规范，同时仍继承你的全局默认值。

在 repository root 中添加覆盖基础 setup 的 AGENTS.md： 

# AGENTS.md

## Repository expectations

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

当特定团队需要不同规则时，在嵌套目录中添加 overrides。例如，在 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 会报告 global file 在第一位、repository root AGENTS.md 在第二位、payments override 在最后。

Codex 一旦到达你的当前目录就会停止搜索，因此请尽量把 overrides 放在靠近专门工作的目录中。

添加 global file 和 payments 专属 override 后，一个示例 repository 如下：

Sample repository
AGENTS.md                       Repository expectations
services/
  payments/
    AGENTS.md                    Ignored because an override exists
    AGENTS.override.md           Payments service rules
    README.md
  search/
    AGENTS.md
    ...

自定义 fallback filenames

如果你的 repository 已经使用不同的文件名（例如 TEAM_GUIDE.md），请把它添加到 fallback list 中，让 Codex 将它视为 instructions file。

编辑你的 Codex configuration： 

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

重启 Codex，或运行一条新命令，让更新后的 configuration 被加载。

现在 Codex 会按以下顺序检查每个目录：AGENTS.override.md、AGENTS.md、TEAM_GUIDE.md、.agents.md。不在此列表中的文件名会被 instruction discovery 忽略。更大的 byte limit 允许在截断前合并更多 guidance。

配置 fallback list 后，Codex 会把 alternate files 视为 instructions：

Fallback file example
TEAM_GUIDE.md                    Detected via fallback list
.agents.md                       Fallback file in root
support/
  AGENTS.override.md             Overrides fallback guidance
  playbooks/
    ...

当你想使用不同 profile（例如项目专属 automation user）时，设置 CODEX_HOME environment variable： 

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

预期：输出会列出相对于自定义 .codex directory 的文件。

验证你的 setup

从 repository root 运行 codex --ask-for-approval never "Summarize the current instructions."。Codex 应该按优先级顺序 echo 来自 global 和 project files 的 guidance。

使用 codex --cd subdir --ask-for-approval never "Show which instruction files are active."，确认嵌套 overrides 会替换更宽泛的 rules。

要 audit Codex 加载了哪些 instruction files，可以选择启用 plaintext TUI log：codex -c log_dir=./.codex-log，并检查 ./.codex-log/codex-tui.log；如果启用了 session logging，也可以检查最新的 session-*.jsonl 文件。

如果 instructions 看起来过期，请在目标目录中重启 Codex。Codex 会在每次运行时（以及每个 TUI session 开始时）重新构建 instruction chain，因此不需要手动清除 cache。

排查 discovery 问题

没有加载任何内容：确认你位于预期 repository 中，并且 codex status 报告的是你期望的 workspace root。确认 instruction files 中有内容；Codex 会忽略空文件。

出现错误 guidance：查找目录树上层或 Codex home 下是否存在 AGENTS.override.md。重命名或删除该 override，即可回退到常规文件。

Codex 忽略 fallback names：确认你已在 project_doc_fallback_filenames 中列出这些名称且没有拼写错误，然后重启 Codex 让更新后的 configuration 生效。

Instructions 被截断：提高 project_doc_max_bytes，或把大型文件拆分到嵌套目录中，以保留关键 guidance。

Profile 混淆：启动 Codex 前运行 echo $CODEX_HOME。非默认值表示 Codex 指向的 home directory 与你编辑的目录不同。

下一步

AGENTS.md Prompting Codex

访问官方 AGENTS.md website 了解更多信息。

阅读 Prompting Codex ，了解与 persistent guidance 搭配良好的 conversational patterns。

站内延伸阅读

站内延伸 把仓库约定写进 AGENTS.md 把长期有效的构建、测试、代码风格和发布约束沉淀在仓库里。
配置文件 Config File 配置文件用于管理 Codex 在项目或个人环境中的默认行为。 权限 Permissions 权限决定 Codex 能访问和修改什么，是团队落地前必须先定清楚的边界。 速度 Speed 速度相关设置适合在任务类型、验证成本和风险等级之间做权衡。 规则 Rules 规则用于把长期约定转成 Codex 可持续遵守的项目行为。 Hooks Hooks Hooks 适合做生命周期里的机械检查、记录和限制，不应承载复杂产品判断。 MCP MCP MCP 让 Codex 按授权连接外部系统和私有知识，而不是依赖复制粘贴上下文。
参考来源 1 条