设定目标，然后放手让它跑

验收清单

• codex 能在终端直接启动，不是 command not found
• 登录完成，/status 能显示当前会话配置
• 你能说出当前的 sandbox_mode 和 approval_policy 分别是什么值
• hello.py 能在你自己的终端里独立跑通
• 你至少经历过一次「它请求升级、你做决定」的完整过程
• git diff 的改动范围与预期一致

常见错误

codex: command not found

安装脚本放二进制的目录不在 PATH 里。重开一次终端；仍不行就重跑一遍同一条安装命令——它同时承担安装、修复与升级三件事。

让它 pip install / npm install，一直失败

默认状态下网络访问是关闭的。要么按提示批准一次升级，要么把装依赖这一步放到会话之外自己先做完，再让它继续。

它改到了工作区之外的文件

说明沙箱被调成了 danger-full-access，或者你批准过一次升级。回到 workspace-write，越界的事让它每次申请、你每次决定。

把审批策略当成沙箱

这是两个独立开关：sandbox_mode 管技术上能碰什么，approval_policy 管什么时候停下来问你。把 approval_policy 设成 never 并不会放宽沙箱边界，反过来也一样。

在一个有未提交改动的仓库里练，改乱了

第一天只在新建的空仓库里练。真实仓库要等你能稳定预测它的边界之后再进。

验收清单

• /init 生成的 AGENTS.md 已按你的项目改写，不是模板原样
• 分层实验验过：子目录的规矩确实压过了根目录的
• codex --profile paranoid 启动后，/status 显示的是 read-only + untrusted
• .codex/config.toml 在受信任项目里确实生效（/status 验证过）
• 你能背出五层配置的优先级顺序
• 有一次 /review 的输出，且你能说清哪几条采纳、哪几条不采纳及原因

常见错误

AGENTS.md 写了，它像没看见

先确认文件名和位置：同一目录下的检查顺序是 AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames 里配的备选名。用了别的文件名又没配备选名，就是不会被读到。

多层 AGENTS.md 里，父目录的规矩赢了

合并方式是从根往下拼接、用空行连起来，越靠后越有分量。想让子目录赢，规矩就得写在子目录那一份里，而不是在父目录里写「子目录例外」。

AGENTS.md 后半截像被吃掉了

合并后的总大小到了 project_doc_max_bytes（默认 32 KiB）就停止追加。把长篇背景挪走，只留它每次都要遵守的硬规矩。

.codex/config.toml 不生效

项目级配置只在受信任的项目里生效。另外要记住它排在 CLI 参数之下、profile 之上——用 --profile 想压过项目配置是压不过的，顺序反了。

profile 建好了但没用上

profile 文件的命名是 ~/.codex/<名字>.config.toml，且必须用 codex --profile <名字> 显式选用，不会自动套用。

验收清单

• codex exec 能在没有人盯着的情况下跑完一个任务并给出结果
• codex resume 能接上之前的会话
• 子 Agent 定义文件三个必填字段齐全，且能被派发到
• /mcp 里能看到你接的服务器
• requirements.toml 已放到正确路径，且反例验过：越权配置被挡下（有终端记录）
• 你能说清 requirements 与 managed defaults 的区别——前者用户改不动，后者只是启动时的初始值
• 你能说出 requirements.toml 里未写的键会怎样（答案：不受约束）

常见错误

requirements.toml 写了，用户还是能改成危险配置

先确认路径对不对（Unix 在 /etc/codex/，Windows 在 %ProgramData%\OpenAI\Codex\）。另外「省略的键保持不受约束」——你没写进去的东西不会被自动收紧，得逐条列出来。

把 managed_config.toml 当成硬约束

它是「托管默认值」，是启动时的初始值，会话里可以被改回来。真正改不动的是 requirements.toml。两个文件放错，等于什么都没管住。

codex exec 在 CI 里卡住不动

非交互环境下没人能批准升级请求。要么把审批策略和沙箱预先配到不需要升级的组合，要么把需要越界的步骤（装依赖、访问网络）拆到 Codex 之外先做完。

/goal 找不到或不生效

它是官方标注的实验特性，需要 goals 功能已启用。另外目标文本有长度上限，超了就写进文件、让目标指向那个文件。

子 Agent 定义写了但派不过去

name 字段才是权威标识，文件名只是给人看的。派发时引用的是 name；description 写得含糊，它也不知道什么时候该轮到自己。

以为把边界交给管理员之后就不用管了

requirements.toml 能约束的键是有清单的（审批策略、审查策略、沙箱模式、权限 profile、联网要求、MCP 允许与阻断清单、插件市场来源、命令规则与文件系统权限等）。清单之外的行为约束只能靠 AGENTS.md 和流程，别把两者混为一谈。