用 Hooks 接入自动检查
基于官方 Codex Hooks 教程，面向新手讲清 hooks 能做什么、不能做什么，以及如何从低风险检查开始。
Hooks 是 Codex 的扩展机制：在会话、提示词提交、工具调用、权限请求、工具调用结束、turn 停止等节点，运行你自己的脚本。它适合做自动检查、日志记录、策略提醒和团队规范执行。
新手要先理解一句话：hook 不是“让 Codex 更聪明”的魔法，它是在 Codex 工作流旁边插入脚本。脚本写错了，轻则打断体验，重则放大权限和隐私风险。
先理解：hooks 适合解决什么问题
Hooks 适合做边界清楚的检查。
例如，用户提交 prompt 前，检查是否误粘贴 API key；工具运行前，检查危险命令；工具运行后，总结输出或补充上下文；turn 停止时，要求再跑一次验证。
Hooks 不适合做复杂业务逻辑，也不适合替代测试框架。它应该只做“是否允许继续”“是否补充上下文”“是否提示用户注意”的轻量决策。
官方文档里，Hooks 需要在 config.toml 打开 codex_hooks feature。Codex 会从活跃配置层旁边发现 hooks.json，也支持 config.toml 里的 inline hooks；已安装 plugins 也可以打包生命周期配置。
怎么判断该挂在哪个事件上
想在用户输入发给模型前检查，用 UserPromptSubmit。适合检查敏感信息、任务范围和是否需要补充上下文。
想在工具执行前检查，用 PreToolUse。适合拦截危险 shell、禁止某些路径、提醒需要确认。
想在权限请求时检查，用 PermissionRequest。适合把团队策略加到审批环节里。
想在工具执行后检查，用 PostToolUse。适合审查命令输出、把额外上下文反馈给 Codex。
想在 turn 结束时检查，用 Stop。适合要求 Codex 继续完成遗漏验证，例如测试还没跑、文档还没更新。
想在 session 启动、恢复或清空时加载上下文，用 SessionStart。
新手第一版怎么做
第一版只做一个只读 hook。比如在 UserPromptSubmit 上检查 prompt 是否包含疑似 key，不修改文件，不运行复杂命令。
第二版再做 PreToolUse，只针对 Bash 或 apply_patch。matcher 要窄，不要全局匹配所有工具。
第三版再做 PostToolUse 或 Stop。这时你已经知道 hook 输入输出长什么样，也知道它对体验的影响。
不要一开始就把所有事件都挂上脚本。官方说明，同一个 event 上多个匹配 command hooks 会并发启动，一个 hook 不能阻止另一个匹配 hook 启动。复杂度会很快上来。
配置位置怎么选
个人规则放在 ~/.codex/hooks.json 或 ~/.codex/config.toml。
项目规则放在仓库 .codex/hooks.json 或 .codex/config.toml。但要注意，project-local hooks 只会在项目 .codex/ layer 受信任时加载。
企业强制规则可以走 managed hooks。官方说明 managed directory 中的 scripts 不由 Codex 分发，需要企业自己的设备管理系统安装和更新。
同一层里不要同时维护 hooks.json 和 inline [hooks]。官方会合并它们并给 warning，但对新手来说这会让问题更难排查。
新手常见坑
- Hook 里做太多事：它应该短、小、可预测，复杂逻辑放到正常工具或测试里。
- matcher 太宽：全局匹配会让每次操作都触发脚本，体验会变慢，也更容易误拦截。
- 忘记并发：多个匹配 hooks 会并发启动，不能假设前一个 hook 已经阻止后一个。
- 把敏感输入写日志：hook 能看到 prompt、cwd、tool input 等信息，日志必须脱敏。
- 以为
PostToolUse能撤销命令：官方说明它发生在工具完成后，阻断不会回滚已经执行的 Bash 命令。 - 忽略
Stop语义：Stop里的 block 不是拒绝本轮，而是让 Codex 继续，用 reason 作为新的 continuation prompt。 - 在不受信任项目里期待 project hook 生效：本地项目 layer 不受信任时不会加载项目 hooks。
怎么验收
先验收加载：启动 Codex 后，确认没有 hooks 配置 warning，目标事件确实触发。
再验收输入：hook 能收到 cwd、event name、tool name 或 prompt 等必要字段，但日志不会保存敏感内容。
再验收决策：允许时不打断流程，拦截时给出人能理解的原因。
再验收失败：hook 脚本异常、超时或输出非法 JSON 时，Codex 的行为符合预期，不会静默吞掉问题。
最后验收边界：关闭该 hook 后，相同任务能恢复正常，说明它没有留下额外副作用。