Codex AGENTS.md 教程：项目规则、目录优先级与可用模板
AGENTS.md 用来告诉 Codex 这个仓库怎么工作：目录在哪里、哪些命令能验证修改、哪些行为必须避免。 它适合长期稳定的项目规则；一次性任务的目标和验收条件仍要写在当前对话里。
本文于 2026 年 10 月 24 日核对 OpenAI AGENTS.md 官方说明。下面的模板为本站编写，可按项目修改；不要把示例命令误认为你的仓库已经提供相应脚本。入门操作先看 Codex 使用教程。
涉及模型网关的项目，可以把 api.clawsocket.com 作为文档核对入口。当前支持的模型、路径、配额、价格、限制，以 api.clawsocket.com 控制台当前显示为准；规则里应要求读取当前配置，避免把模型 ID、Key 或价格长期硬编码。
1. AGENTS.md 应该写什么
最有价值的是能影响具体操作、又不需要每次重复说明的内容：
| 内容 | 可执行的写法 | 不够明确的写法 |
|---|---|---|
| 项目结构 | 文档在 docs/，主题在 docs/.vitepress/ | 理解整体架构 |
| 验证 | 修改文档后运行 npm run docs:build | 保证代码质量 |
| 修改范围 | 不手改 dist/ 构建产物 | 不要乱改 |
| 密钥 | API Key 从环境变量读取，不输出其值 | 注意安全 |
| 交付 | 列出改动文件、已运行检查和未验证项 | 完成后总结 |
规则应对应仓库事实。项目没有 lint，就不要为了让模板完整而写“提交前必须 lint”；先说明可用检查和缺口。
2. 文件放在哪里，如何覆盖
按当前官方发现机制，可以把规则理解为从通用到具体逐层组合：
- 全局指令来自
CODEX_HOME，默认目录为~/.codex。 - 项目指令从项目根目录沿路径读取到当前工作目录。
- 同一目录优先选
AGENTS.override.md，其次AGENTS.md，再考虑配置的 fallback 文件名；每层最多选一份。 - 更靠近当前目录的指令后加载，用于覆盖较宽泛的指导。
目录示例：
text
repository/
├── AGENTS.md
├── docs/
│ ├── AGENTS.md
│ └── posts/
└── services/
└── billing/
└── AGENTS.override.md从根目录启动时，不要假设所有子目录规则都会在初始发现阶段全部载入。开始任务时说明目标目录，并要求 Codex检查目标路径上的规则；专门处理子项目时可从对应目录启动。不要让两层规则同时要求不同包管理器，却不说明作用范围。
3. 一个 VitePress 项目模板
下面的构建命令适用于配置了 docs:build 脚本的项目。复制前先核对 package.json：
md
# 项目约定
## 结构
- 文档源文件在 docs/。
- 文章在 docs/posts/，静态图片在 docs/public/images/。
- 不手工编辑 docs/.vitepress/dist/。
## 内容
- 页面先解释适用边界，再给步骤。
- 站内使用相对 Markdown 链接。
- 图片提供准确的替代文本，注明示意图与实测截图的区别。
- 涉及产品当前能力时核对官方文档，并记录核对日期。
## 验证与交付
- 修改文档后运行 npm run docs:build。
- 检查新增页面、图片和站内链接是否能在构建结果中找到。
- 交付时列出已通过、失败和未执行的检查。
- 提交前阅读 git diff，排除密钥和构建产物。这类规则能把“写完 Markdown”变成“文章可构建、图片可访问、链接有入口”。但如果站点尚未配置正确的发布流程，构建通过仍不能证明线上页面已经部署。
4. API 项目增加哪些约束
模型接入项目可以补一段与你的实际运行环境相符的规则：
md
## API 配置
- 从环境变量读取 API Key、Base URL 和模型 ID。
- 不打印认证头、完整密钥或包含敏感输入的请求体。
- 修改 provider 前保留可回滚的配置记录，不复制密钥到仓库。
- 先验证最小请求，再验证流式响应、工具调用和连续多轮。
- 记录错误码、脱敏 request ID、耗时和验证时间。
- 没有真实凭证或网络条件时，明确标注未实测。这段规则不会给网关增加能力。协议怎么配、哪些检查不可省略，继续看 Codex API 中转站配置。
5. 怎么确认规则生效
先保存文件，再开启新会话进行小范围验证。可以输入：
text
请只读列出当前任务适用的项目指令来源和实际路径。
说明构建命令、禁止修改的目录、交付时必须报告的检查。
如果没有读取到 AGENTS.md，请明确说明，不要推测。接着让它处理一个只涉及文档的小任务，检查是否使用真实构建命令、是否避免写入产物目录、是否报告未执行项。模型复述规则是检查线索，最终仍要看行为和文件差异。
出现不生效时按下面顺序查：
| 检查 | 常见原因 | 修正方式 |
|---|---|---|
| 实际工作目录 | 在另一个 checkout 或 worktree 中 | 核对绝对路径 |
| 文件名 | 写成 agents.md 或附加 .txt | 使用准确名称 |
| 同目录 override | AGENTS.override.md 被优先采用 | 检查该文件是否仍需要 |
| 会话创建时间 | 规则在旧会话启动后改变 | 新开会话重新验证 |
| 指令体积 | 长文超出加载限制 | 精简主规则，把细节放到按需文档 |
| 组织配置 | 管理策略限制用户配置 | 对照管理员配置确认 |
6. AGENTS.md、提示词与配置文件怎么分工
AGENTS.md 说明仓库如何工作；当前提示词说明本次要做什么；config.toml 管理客户端设置和 provider。密钥应留在安全的凭证来源中。把 API Key 写进规则文件，既不能提高指令优先级，也会增加泄漏风险。
规则文件同样不能替代权限边界或测试。即使写了“不要修改生产”，生产凭证仍应隔离；即使写了“必须构建”，也需要检查实际输出。
7. 一次迁移只改一个维度
接手新仓库时，先记录现有命令和目录，再补规则，然后验证一次小任务。不要同时升级依赖、迁移 provider、重写目录结构并更改交付规则，否则很难定位失败来源。
继续阅读 CLI 安装与登录、完整使用流程和 费用与任务预算。
FAQ：AGENTS.md 规则文件
AGENTS.md 是 Codex 必需文件吗？
不是。没有 AGENTS.md 时，Codex 仍可根据当前提示词和客户端配置工作。它的作用是保存长期、可复用、能检查的项目约定，例如目录位置、构建命令、密钥处理和交付格式。首次创建后要在新会话中验证规则是否被读取，不能只因为文件存在就认为已经生效。
根目录和子目录都有 AGENTS.md，哪个规则优先？
按官方发现机制，规则会沿项目路径从通用位置组合到更具体的位置；越靠近当前工作目录的规则，越适合补充或覆盖上层约定。同一目录存在 AGENTS.override.md 时，应先检查它是否被优先采用。实际生效内容还受启动目录、组织配置和文件加载限制影响，因此应要求 Codex列出实际读取的路径。
应该把 API Key 写进 AGENTS.md 吗？
不应该。规则文件可能被提交、同步或被不需要凭证的任务读取。AGENTS.md 只写“从环境变量读取 Key、不要打印认证头、日志需要脱敏”等约束；密钥放在安全的凭证管理方式中。模型 ID、Base URL 和配额也可能变化，要求任务开始时核对当前控制台，不要把过时值写成永久规则。
AGENTS.md 写得越详细越好吗？
不是。优先写会改变行为、能被验证且长期稳定的规则。目录结构、真实构建命令、禁止修改的目录、密钥处理和交付要求通常比泛泛的“保证质量”有用。过长的文件会增加阅读负担，还可能与子目录规则或当前任务冲突；详细背景可以放到按需阅读的文档。
怎样确认 Codex 真的遵守了规则？
先开新会话，让它只读列出适用规则的文件路径、构建命令、禁止修改的目录和交付要求。然后安排一个很小的文档任务，检查它是否使用真实命令、是否避开构建产物、是否报告未执行项。最终以文件差异和命令输出判断，不以它复述规则的流畅程度判断。
AGENTS.md 能替代权限控制和测试吗？
不能。规则文件是给 agent 的工作说明，不能替代操作系统权限、仓库访问控制、生产环境隔离或自动化测试。即使写了“不要修改生产”，仍应让生产凭证不可被普通任务读取；即使写了“必须测试”，仍需实际运行并记录结果。