主题
OpenAI Codex：AGENTS.md不生效怎么办？作用域、优先级与规则冲突教程【2026年7月】
文章更新时间：2026-7-30
Codex/GPT API 教程主要面向需要接入 GPT、Claude、Gemini 等模型、或用 AI 编程智能体处理项目代码的开发者。AGENTS.md 是放在仓库里、用来保存可持续复用开发约定的 Markdown 文件，Codex 在处理任务时会参考它来了解你的项目规范。本文聚焦一个具体场景：你已经写了 AGENTS.md，但 Codex 好像没按规则来。文章会整理排查顺序、作用域与优先级概念、规则冲突改写、最小可验证示例，以及和 API 中转、模型选择相关的开发避坑。先给结论：AGENTS.md 不生效时，先查文件名是否严格为 AGENTS.md，再查放置目录与目标文件路径是否在同一作用域，再看上层与下层规则是否互相矛盾，最后区分你写的是一次性提示还是持久项目规则。 所有支持范围、读取规则、命令和权限细节，均以 OpenAI Codex 官方文档 和 openai/codex 仓库 当前说明为准。
第三方工具参考（非官方）
ZeoGPT：zeogpt.com 偏 Codex、代码开发和高频项目工作流，适合代码生成、项目修改、开发辅助和中文任务描述。
ZeoAPI：zeoapi.com 面向开发者的多模型 API 接入平台，适合 GPT、Claude、Gemini、Codex、自动化脚本和原型测试。
说明：以上为第三方工具或平台，不是 OpenAI、Anthropic、Google 官方入口。使用前请自行查看服务说明、隐私政策和账号规则。
如果你需要中文任务描述、代码生成和高频项目修改辅助，可以把 zeogpt.com 作为工具选择之一；它不能替代 AGENTS.md 的排查，也和 OpenAI 官方没有从属关系，只是开发流程里的一个补充工具。
先给结论：AGENTS.md 不生效最常见的 6 个原因
在深入之前，先把最容易踩的坑列清楚。遇到「规则没生效」，多数情况能在下面 6 条里对号入座：
- 文件名不对：文件应严格命名为
AGENTS.md，大小写、拼写、扩展名都要正确。写成agent.md、AGENT.md、Agents.MD或agents.markdown，都可能不被识别。 - 放错目录：文件放到了 Codex 不会读取的位置，比如放进了
.gitignore排除的目录，或放到与目标文件毫不相干的层级。 - 目标文件不在作用域内：你在
src/下写了规则，但这次任务修改的是packages/api/下的文件，规则和目标不在同一路径分支上。 - 规则太空泛：写的是「保持高质量代码」「遵循最佳实践」这类口号，Codex 无法转化成可执行动作。
- 上层与下层规则冲突：根目录规则和子目录规则互相矛盾，导致行为不符合预期。
- 把一次性任务写进了持久规则：像「这次只改登录 bug，别动别的」这种只适用于单次任务的内容，被塞进了长期项目约定里。
后面每一节会分别展开排查方法。需要强调：AGENTS.md 在不同 Codex 界面、版本和运行入口下的读取行为不一定完全一致，本文提供的是通用排查思路，具体支持范围请以官方文档为准。
AGENTS.md 是什么，不是什么
AGENTS.md 的定位是「仓库内可持续复用的开发约定」。它适合记录那些每次任务都成立、对整个项目或某个目录长期有效的规范，比如项目用什么包管理器、测试命令怎么跑、哪些目录不允许改、提交前要做哪些检查。
它不是以下这些东西：
- 不是密钥配置文件。API Key、密码、令牌、账号信息、私有服务凭据都不应该写进去，这些应放在环境变量或团队的安全配置系统中。
- 不是一次性任务清单。「这次帮我把这个函数重命名」属于当前任务提示，不该写成持久规则。
- 不是营销文案或与仓库无关的说明。
把 AGENTS.md 当成「新同事入职文档」来理解比较贴切：你希望任何人（或任何智能体）第一次接触这个仓库时就该知道的工程约定，才值得写进去。
排查前准备：确认 Codex 版本、运行入口和官方文档
排查之前，先确认三件事，避免在错误的前提下折腾：
- 当前使用的 Codex 入口：是 CLI、IDE 插件还是云端环境？不同入口对项目文件的读取方式可能有差异。
- 当前版本：老版本和新版本对 AGENTS.md 的处理可能不同。查看版本的方式请参考 openai/codex 仓库说明，不要凭记忆套用固定命令。
- 官方文档的当前描述：AGENTS.md 支持的具体范围、读取规则会随版本更新，务必以 developers.openai.com/codex 和 github.com/openai/codex 为准。
如果你还没完成安装或登录配置，可以先看 Codex 下载、安装与环境准备教程 和 Codex CLI 登录与 API 配置教程，把基础环境跑通再来排查规则问题。
检查文件名与位置：AGENTS.md 应该放在哪里
第一步永远是确认文件名和位置。下面是一个示意项目树，展示不同层级放置 AGENTS.md 的常见做法：
my-project/ ├── AGENTS.md # 根目录：项目级通用约定 ├── package.json ├── src/ │ ├── AGENTS.md # src 目录：源码相关约定 │ └── index.ts ├── packages/ │ └── api/ │ ├── AGENTS.md # 子包：更具体的 API 层约定 │ └── server.ts ├── docs/ │ └── AGENTS.md # 文档目录：文档写作约定 └── tests/ └── AGENTS.md # 测试目录：测试相关约定 排查要点：
- 文件名必须严格是
AGENTS.md，逐字符核对。 - 根目录的 AGENTS.md 通常覆盖面最广；越靠近目标文件的目录，规则越贴近该目录的实际情况。
- 如果你的规则针对某个子模块，把它放进那个子模块的目录里，比放在根目录更容易命中目标文件。
- 确认文件没有被工具链忽略，也确实已经提交进仓库（如果你依赖 git 状态的话）。
理解 AGENTS.md 作用域：目标文件路径决定会读到哪些规则
作用域是最容易误判的一环。核心逻辑是：Codex 处理某个文件时，通常会参考从根目录到该文件所在目录这条路径上的 AGENTS.md。也就是说，规则能不能命中，取决于「你这次改的文件」在哪，而不是「你觉得规则应该管哪」。
下面这张表帮你判断不同目录规则的适用场景和常见误判：
| 规则所在目录 | 适用场景 | 通常会影响的目标文件 | 常见误判 |
|---|---|---|---|
根目录 AGENTS.md | 全项目通用约定：包管理器、提交规范 | 仓库内各处文件 | 以为它会被子目录规则完全覆盖，其实是叠加关系 |
src/AGENTS.md | 源码风格、模块划分 | src/ 下的文件 | 以为它能管到 tests/ 或 docs/，实际不在同一路径分支 |
docs/AGENTS.md | 文档语气、格式、目录结构 | docs/ 下的文档 | 把代码测试命令写进这里，改代码时读不到 |
tests/AGENTS.md | 测试框架、命名、覆盖率要求 | tests/ 下的测试文件 | 以为改 src/ 代码时会自动套用测试目录的规则 |
一句话总结：如果你的规则「没生效」，先确认这次任务改的文件路径，是否真的经过了你写规则的那个目录。这就是 AGENTS.md 作用域的核心。
理解 AGENTS.md 优先级：更接近目标文件的规则通常更具体
当同一件事在多层 AGENTS.md 里都提到时，就涉及优先级。通用理解是：更接近目标文件的目录级规则往往更具体，应当作为对上层规则的补充或细化，而不是与上层规则打架。
举例：根目录规则说「所有代码用 2 空格缩进」，而 packages/legacy/AGENTS.md 说「这个历史模块保持 4 空格缩进」。这是合理的分层——下层针对特定目录给出更具体的例外，两者不矛盾，因为作用范围不同。
但要避免这种写法：根目录说「提交前必须跑 全量测试」，子目录又说「不要跑测试」。这就是直接冲突，容易让行为不可预期。正确做法是让下层规则补充而非否定上层，比如下层写「本目录测试可只跑 该目录的测试子集，但根目录的提交前检查仍需执行」。
需要提醒：不要绝对化地认为所有 Codex 实现都用完全相同的优先级逻辑。分层理解是通用心智模型，具体行为以当前官方文档为准。想深入项目规则设计，可参考 Codex 项目规则与团队协作最佳实践。
规则冲突怎么写才不互相抵消
规则冲突是 Codex 指令冲突里最典型的一类。下面用「坏例子」和「改写后例子」对比说明：
缩进风格
- 坏例子（根目录与子目录矛盾）：根目录「统一 2 空格」，子目录「统一 4 空格」，没说明范围。
- 改写后：根目录「默认 2 空格缩进」，子目录「
packages/legacy/下的历史文件保持 4 空格，其余遵循根目录约定」。
测试命令
- 坏例子：根目录「提交前跑测试」，子目录「跳过测试」。
- 改写后：根目录「提交前运行项目测试命令（以 package.json 脚本为准）」，子目录「本目录改动可先运行该目录相关测试子集做快速验证，提交前仍执行根目录的完整检查」。
禁止编辑目录
- 坏例子：只写「不要动核心代码」，没说哪些是核心。
- 改写后：「不要编辑
src/generated/和dist/，这些是自动生成产物；如需变更请修改生成配置」。
提交前验证
- 坏例子：「确保代码没问题再提交」。
- 改写后：「提交前依次执行：安装依赖、运行 lint、运行测试；任一步失败则不要提交」。
规律很清楚：把冲突拆成「不同作用范围」或「明确的补充关系」，并写成可执行动作，冲突就消失了。
一次性提示与持久规则的边界
这是很多人忽略的一点。当前任务提示（你在对话里说的「这次帮我改 X」）和 AGENTS.md 的定位完全不同：
- 一次性提示：只对本次需求有效，比如「这次只修复登录超时 bug，不要重构其他代码」。这类内容应该写在任务描述里，说完这次就结束。
- 持久规则：长期成立的约定，比如「所有网络请求都要加超时处理」。这类才适合写进 AGENTS.md。
如果你把「这次只改某个 bug」写进 AGENTS.md，下次做别的任务时它还在，就会造成困惑甚至误导。判断标准很简单：问自己「三个月后做另一个功能时，这条还成立吗？」成立就写进 AGENTS.md，只对当前任务成立就放在任务提示里。
最小可验证 AGENTS.md 示例
下面是一个短小、可验证的示例。它包含项目背景、编辑边界、命令、测试和提交前检查，不含任何密钥或空泛口号。请注意：命令要以你项目实际使用的为准，本示例仅演示结构，不代表适用于所有 Codex 界面。
项目约定
背景
这是一个 TypeScript 单体仓库，使用 pnpm 管理依赖。
编辑边界
- 不要编辑
dist/和src/generated/，它们是构建产物。 - 修改
packages/api/时，不要改动packages/ui/下的文件。
常用命令
- 安装依赖：
pnpm install - 启动开发：
pnpm dev - 构建：
pnpm build（命令以 package.json 中的 scripts 为准）
测试
- 运行测试：
pnpm test - 新增功能需补充对应测试文件，放在同名
.test.ts里。
提交前检查
- 运行
pnpm lint，无报错。 - 运行
pnpm test，全部通过。 - 确认没有改动编辑边界内列出的禁止目录。 这个文件之所以「可验证」，是因为每一条都能被检查：命令能跑、边界能核对、检查步骤有明确顺序。这正是让 Codex 项目规则真正生效的关键。
实战排查流程：从一个不生效案例定位问题
以下为泛化示例，用于说明排查思路，不代表任何真实用户的具体数据或结论。
场景：某开发者在仓库根目录的 AGENTS.md 里写了「提交前跑 pnpm test」。但他这次修改的是 packages/api/ 下的文件，而 packages/api/AGENTS.md 里写着「本目录使用 pnpm test:api 做快速验证」。结果他发现 Codex 只跑了 test:api，没跑全量测试，和他的预期不符。
排查过程：
- 确认文件名——两个文件都叫
AGENTS.md，没问题。 - 确认目标文件路径——这次改的是
packages/api/，所以子目录规则会被读到。 - 检查规则冲突——根目录说跑
pnpm test，子目录说跑test:api，两者在「提交前跑什么测试」上产生了覆盖式冲突，下层规则事实上替代了上层。 - 定位根因——下层规则写成了替代关系，而不是补充关系。
解决办法：把子目录规则改写为补充关系：「本目录开发中可先运行 pnpm test:api 做快速验证，提交前仍需执行根目录要求的 pnpm test」。改完后，两层规则不再互相抵消。
这个案例说明：所谓「不生效」，很多时候是「被更近的规则覆盖了」，而不是「Codex 没读到规则」。
适合写进 AGENTS.md 的规则清单
下表列出推荐写进 AGENTS.md 的内容、原因，以及对应的反例：
| 推荐写法 | 为什么 | 反例 |
|---|---|---|
可执行命令（如 pnpm build） | 能被直接执行和验证 | 「记得构建一下」 |
| 编辑边界（禁止改的目录） | 明确划定可动范围 | 「别乱改代码」 |
| 验证步骤（lint、test 顺序） | 提供可复现的检查流程 | 「确保没问题」 |
| 代码风格（缩进、命名规则） | 具体、可对照 | 「代码要优雅」 |
| 依赖管理（用哪个包管理器） | 避免混用工具 | 「装依赖就行」 |
| 生成文件处理（哪些是产物） | 防止误改自动生成内容 | 「注意生成的文件」 |
原则始终一致：可执行、可验证、有明确边界。写代码审查和测试流程时可以配合 使用 Codex 做代码审查、重构和测试的工作流 一起看。
不适合写进 AGENTS.md 的内容
以下内容不要放进 AGENTS.md：
- API Key、密码、令牌：这是安全红线，应放在环境变量或安全配置系统里，参考 API Key、令牌和配置文件安全管理教程。
- 账号信息、私有凭据：同上，涉及敏感信息一律不写进仓库文件。
- 私有服务地址：内网地址、数据库连接串等不应硬编码在这里。
- 一次性临时任务：只对本次需求有效的内容放任务提示里。
- 模糊口号：「写高质量代码」「保持最佳实践」这类无法执行的句子。
- 与仓库无关的营销文案：AGENTS.md 是工程文档，不是宣传页。
再次强调风险：把密钥写进 AGENTS.md 会随仓库一起被读取、被提交、被同步，极易泄露。安全边界相关内容可参考 Codex 权限、沙箱与安全边界说明。
Codex 项目规则与 API 接入工作流如何配合
实际开发中，你可能同时在做 GPT、Claude、Gemini 的原型测试、Codex 代码改动和自动化脚本。这时把两类信息分开管理会更清晰：
- 可复用工程规范（怎么跑测试、哪些目录别动、代码风格）写进 AGENTS.md，让智能体每次都遵守。
- 模型接入配置和密钥（各家 API 的 endpoint、Key、超时设置）放进安全配置系统或环境变量，绝不写进 AGENTS.md。
如果你要在一个环境里同时测多个模型，zeoapi.com 这类多模型 API 接入平台可以作为原型测试环境的选择之一，方便对比 GPT、Claude、Gemini 在同一任务上的表现（以平台实际显示的支持范围为准）。它只是测试环境的一个补充，不是唯一入口，也不解决 AGENTS.md 本身的排查问题。多模型接入的整体思路可参考 GPT、Claude、Gemini 与 Codex API 接入指南。
常见错误与排查表
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 写了规则但 Codex 改了不该改的文件 | 编辑边界没写清，或写成了模糊描述 | 用具体目录路径列出禁止编辑范围 |
| 规则要求跑测试但没跑 | 命令不可执行，或被下层规则覆盖 | 核对命令是否真实存在、是否有冲突规则 |
| 子目录规则没按预期生效 | 目标文件不在该子目录路径分支上 | 确认这次改动的文件是否真的在该目录下 |
| 规则太长导致重点不清 | 内容堆砌、缺乏结构 | 精简为可执行条目，删掉口号 |
| 根目录规则「失效」 | 被更近的下层规则覆盖 | 改成补充关系而非替代关系 |
| 文件完全没被读到 | 文件名拼错或位置错误 | 逐字符核对 AGENTS.md 并确认目录 |
遇到更广泛的运行报错，可对照 Codex 常见报错与排查清单。
使用前检查清单
在提交 AGENTS.md 之前，逐条过一遍：
- [ ] 文件名严格为
AGENTS.md，无拼写和大小写错误。 - [ ] 文件放在与目标文件同一路径分支的目录里。
- [ ] 每条规则都是可执行、可验证的，没有空泛口号。
- [ ] 上层和下层规则是补充关系，不互相矛盾。
- [ ] 没有把一次性任务写成持久规则。
- [ ] 文件里不含任何密钥、密码、令牌或私有凭据。
- [ ] 命令、包名、脚本以项目实际配置为准，已核对过。
- [ ] 已参考官方文档确认当前版本的读取行为。
真实场景案例：多人协作时的规则冲突
以下为泛化示例，不代表真实团队数据。
一个三人小团队在同一个 monorepo 里协作。前端同学在 packages/ui/AGENTS.md 写了「组件必须配 Storybook 故事」，后端同学在根目录 AGENTS.md 写了「所有改动提交前跑 pnpm test」，还有人在 packages/api/AGENTS.md 写了「本目录跳过 Storybook 相关检查」。
当 Codex 处理 packages/ui/ 下的任务时，它读到的是根目录 + packages/ui/ 的规则，Storybook 要求成立；处理 packages/api/ 时，读到的是根目录 + packages/api/ 的规则，Storybook 跳过、但根目录的测试要求仍在。这套结构之所以能工作，是因为每条规则的作用范围都界定清楚，且下层没有否定根目录的通用要求。团队把「跳过」改成了明确的范围限定后，规则冲突就不再出现。这说明合理的作用域划分，比堆砌更多规则更重要。
FAQ
AGENTS.md 必须放在根目录吗？
不一定。根目录适合放全项目通用约定，子目录适合放更具体的约定。放在哪取决于你的规则想覆盖哪些文件。具体读取范围以当前官方文档为准。
子目录规则会覆盖根目录规则吗？
更接近目标文件的规则通常更具体，可以对上层规则做补充或给出局部例外。但应把它设计成补充关系而非直接否定，否则容易出现指令冲突。是否为严格覆盖以官方文档说明为准。
能不能把 API Key 放进 AGENTS.md？
不能。密钥、密码、令牌、私有凭据都不应写进仓库文件，应放在环境变量或安全配置系统中，并遵守团队安全规范。
AGENTS.md 能用中文写吗？
可以用中文描述规则，只要内容清晰、可执行即可。命令、路径、包名建议保持原样，避免翻译造成歧义。
一个仓库能有多个 AGENTS.md 吗？
可以在不同目录放多个，用来分别约定各自作用域内的规范。注意让它们之间是分层补充关系，避免互相矛盾。
规则冲突时应该怎么办？
先确认冲突的两条规则作用范围是否不同；如果范围相同就必须二选一或合并。把规则改写成「不同目录、不同场景」的补充关系，是化解冲突最有效的方式。
一次性提示和 AGENTS.md 哪个更适合放临时需求？
临时需求（只对本次任务成立）放任务提示里；长期成立的约定才写进 AGENTS.md。判断标准是「换个任务时这条还成立吗」。
怎么验证 Codex 确实读到了我的规则？
可以在任务中让它按某条具体、可观察的规则执行（比如指定的测试命令或编辑边界），看行为是否符合。如果不符，再按本文的文件名、目录、作用域、冲突顺序排查。具体验证方式以当前 Codex 界面为准。
AGENTS.md 越详细越好吗？
不是。过长会稀释重点，导致关键规则被淹没。优先保留可执行、可验证的核心条目，删掉口号和重复内容。
风险提示
本站为教程与导航类内容，不是 OpenAI、Anthropic、Google 的官方入口，也不提供模型对话、代码执行或 API 调用功能。文中提到的 ZeoGPT、ZeoAPI 等均为第三方工具或平台，与上述公司没有从属或合作关系。使用任何第三方平台前，请自行评估账号、隐私、数据和支付风险，并阅读其服务条款与隐私政策。涉及 Codex 的命令、版本、权限、支持范围和安全策略，务必以 OpenAI Codex 官方文档 和 openai/codex 仓库 当前内容为准，本文不对功能、价格、额度或地区可用性做任何承诺。详见 免责声明 与 隐私说明。
相关阅读
- OpenAI Codex：VS Code扩展登录失败、授权循环与账号切换排查【2026年7月】
- Codex 中文文章库
- OpenAI Codex CLI：Windows安装、ChatGPT登录、PATH与首次运行排错【2026年7月更新】
- OpenAI Codex API配置教程：ChatGPT登录、API Key、config.toml与安全排错【2026年7月更新】
- OpenAI Codex下载：官网、App、CLI、Windows与安装方式核对【2026年7月更新】
- OpenAI Codex安装部署指南：Windows、macOS、Linux、CLI与首次项目【2026年7月更新】
- Codex CLI怎么更新？版本检查、升级失败、降级与卸载教程【2026年7月】
- Codex AGENTS.md怎么写？项目规则、命令、目录边界与分层配置教程【2026年7月】