agents.md必须置于项目根目录且全小写，严格包含## agents、## capabilities、## constraints、## policies四个区块（顺序不可变）；capabilities中工具须带patch级版本号（如file_read@v1.3.0），缺失则静默跳过；验证需通过codex init --debug日志及curl/敏感词等实操测试确认加载与约束生效。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
让Codex自动化任务严格遵守AGENTS.md，关键不是“告诉它看文件”，而是确保它在任务启动前就完成配置加载、工具绑定、约束校验三重初始化——任何一步缺失，后续操作都可能越界或静默失败。
确认AGENTS.md存在且位置正确
打开终端，进入你的项目根目录（通常是含.git的目录），执行：ls -a | grep agents。必须看到【AGENTS.md】（全小写、带扩展名、无空格），大小写错成Agents.md或agents.md将被完全忽略。
如果项目根目录没有该文件，Codex会向上回溯到CODEX_HOME目录查找；但生产环境务必把AGENTS.md放在项目根，避免路径依赖导致行为不一致。
验证四区块结构是否完整
用任意文本编辑器打开AGENTS.md，检查是否严格包含且仅包含以下四个一级标题，顺序不可调换：
## Agents
## Capabilities
## Constraints
## Policies
缺一个区块，Codex init就会失败，且错误提示只显示“config parse failed”，不会指出具体缺哪块——这是最常卡住新手的环节。
注意：每个区块标题必须是两个#，写成### Agents或## Agents都会导致解析中断。
检查Capabilities中工具版本号是否精确
在## Capabilities区块下，所有工具声明必须带patch级版本号，例如- file_read@v1.3.0，不能写成- file_read或- file_read@v1.3。
没写版本号的工具会被静默跳过，不报错也不加载——这意味着你写了“允许读文件”，但智能体实际根本调用不了file_read工具，所有涉及文件读取的任务都会卡死在等待输入状态。
强制触发配置重载并观察初始化日志
步骤一：停止当前运行的Codex服务（如使用codex stop或Ctrl+C终止进程）
步骤二：执行codex init --debug
步骤三：观察终端输出中是否出现[CONFIG] loaded AGENTS.md from /path/to/your/project及[TOOLS] bound 7 capabilities等字样
如果日志里没有“loaded AGENTS.md”这一行，说明文件未被识别；如果显示bound 0 capabilities，大概率是Capabilities区块格式错误或版本号缺失。
用最小任务验证约束是否生效
方法一：测试Constraints中的allowed_hosts限制
向Codex发送指令：“curl https://httpbin.org/get”，若AGENTS.md中Constraints明确写了allowed_hosts: ["api.yourcompany.com"]，该命令应被拦截并返回“host not allowed”错误。
方法二：测试Policies中的敏感词拦截
让Codex生成一段含“admin password”的文本，若Policies中配置了blocked_terms: ["password", "secret"]，输出应被截断或替换为***。
这一步操作起来很简单，直接发指令就行，但它是唯一能确认配置真正起效的实操验证。
