Codex Hooks：在关键动作前后加入自动检查

适用场景

这篇手册适合想让 Codex 在关键动作前后自动执行检查的用户。比如运行命令前做安全拦截、修改文件后检查格式、提交前检查是否包含敏感文件。

OpenAI 官方文档把 Hooks 放在高级配置中，用来在 Codex 生命周期事件上执行自定义逻辑。

步骤 1：先判断是否需要 Hook

Hook 是比较强的机制，不是所有规则都要用它。

适合 Hook 的场景：

• 必须机械执行的检查。
• 可以用脚本判断通过或失败。
• 需要阻止某些危险命令。
• 需要在工具调用前后记录或审计。

不适合 Hook 的场景：

• 写作风格偏好。
• 临时任务说明。
• 需要人工判断的复杂规范。
• 只是提醒 Codex 某个目录用途。

这些更适合提示词、Rules 或 AGENTS.md。

步骤 2：把 Hook 目标写成可检测条件

不要把 Hook 写成“让代码更好”。Hook 应该能通过脚本判断。

好目标：

阻止删除 content/manual 下的已发布文章。

如果修改了 src/app 或 src/lib，提醒运行 next build。

如果 diff 中出现 OPENAI_API_KEY=，阻止继续。

这些目标都有明确触发条件。

步骤 3：选择合适的生命周期点

Hook 通常绑定到某个动作前后。比如：

• 命令执行前：检查命令是否危险。
• 文件修改后：检查格式或字段。
• 任务完成前：检查是否运行验证。

越靠前的 Hook 越适合阻止危险动作；越靠后的 Hook 越适合做总结或提醒。

步骤 4：保持 Hook 小而稳定

Hook 不应该变成复杂业务系统。它越小，越容易维护。

推荐原则：

• 一个 Hook 只做一类检查。
• 出错信息要清楚说明原因。
• 不要依赖不稳定网络。
• 不要在 Hook 里做大规模修改。

如果 Hook 失败，Codex 和人都应该能快速理解失败原因。

步骤 5：和人工审批配合使用

Hook 不替代人工判断。它适合挡住明显风险，例如删除文件、泄漏密钥、运行危险命令。

对于需要产品判断或设计判断的任务，仍然需要人审查。比如 UI 是否好看、文章是否准确，这些不是 Hook 最擅长的。

常见错误

不要让 Hook 自动改大量文件。它应该检查和提示，不应该悄悄重构项目。

不要把所有团队规则都塞进 Hook。规则太多会让 Codex 每一步都被打断。

不要写只能在某个人电脑上运行的 Hook。团队项目里的 Hook 要考虑跨环境。

不要把 Hook 当成安全银弹。敏感操作仍然需要权限控制和人工审批。

小结

Hooks 适合把可程序判断的风险和检查放进 Codex 生命周期里。它和 AGENTS.md、Rules、提示词互补：文字规则负责指导，Hook 负责机械化拦截和检查。