Codex Hooks 怎么用？PreToolUse、PostToolUse、PermissionRequest 与自动检查指南

先说结论：Hooks 是自动化扩展点，不是完整安全边界

Codex Hooks 能在会话开始、提交提示、工具调用前后、权限请求、压缩、子代理停止或主线程结束等阶段运行命令或 MCP 工具。常见用途包括阻止误贴密钥、记录审计、扫描补丁和在任务结束时检查标准。

Hook 可以拒绝或改写部分操作，也可以向模型提供上下文，但并非所有工具路径都覆盖，多个匹配 Hook 还可能并发运行。安全设计仍要依赖沙箱、权限、网络限制、最小凭证和外层隔离。

一、Codex 从哪里加载 Hooks

Codex 会在活动配置层旁查找 hooks.json，也可从 config.toml 内联 [hooks] 配置读取。插件还能通过清单或默认 hooks/hooks.json 提供 Hook。项目本地 Hook 只有在项目 .codex/ 配置层受信任时才加载。

个人通用 Hook 适合放在用户层，团队强制策略放在受管理配置，仓库专用检查放在项目层。脚本路径应从 Git 根目录或稳定绝对位置解析，避免从子目录启动时找错文件。

二、为什么新 Hook 需要信任审查

非托管 Hook 在运行前需要用户检查并信任其精确定义。Codex 按当前定义的哈希记录信任，Hook 新增或改变后会重新标记为待审查，并在信任前跳过。CLI 可用 /hooks 查看来源、审查、信任或禁用。

这一步很重要，因为 Hook 本身可以执行本地命令、读取输入并影响流程。不要把来源不明的 hooks.json 直接设为可信，也不要仅因为仓库能编译就默认 Hook 安全。

三、先理解常见生命周期事件

SessionStart 适合加载项目上下文，UserPromptSubmit 可检查用户输入，PreToolUse 在工具执行前拦截，PermissionRequest 在即将请求审批时运行，PostToolUse 在工具产生结果后运行，Stop 可做结束检查。

PreCompact 与 PostCompact 处理上下文压缩，SubagentStart 和 SubagentStop 面向子代理，SessionEnd 在主线程真正结束时运行。事件触发时机不同，选错事件会导致检查太早或无法撤销副作用。

四、matcher 怎样筛选事件

matcher 是正则字符串，用于筛选部分事件。PreToolUse、PostToolUse 和 PermissionRequest 通常按工具名匹配，例如 Bash、apply_patch、Edit、Write 或具体 MCP 工具名；SessionStart 可按 startup、resume、clear、compact 匹配。

并非所有事件都支持 matcher。UserPromptSubmit、Stop 和 Interrupt 当前会忽略 matcher。配置前应查当前官方表格，避免以为规则已限定范围，实际却对每次事件都运行。

五、PreToolUse 适合做什么

PreToolUse 在受支持的工具执行前收到 tool_name 与 tool_input，可检查 shell 命令、补丁、MCP 参数和其他本地函数工具。它可用于阻止危险目标、改写可控参数或为调用添加策略信息。

阻止前要返回官方支持的结构，并给出清楚原因与安全替代方案。规则应尽量确定、快速且可测试；复杂模糊判断可能误阻塞正常开发，不能只靠模型猜测路径是否安全。

六、PermissionRequest 与审批流程

PermissionRequest 只在 Codex 即将请求权限时触发，例如沙箱升级或受管理网络审批。Hook 可以允许、拒绝或不作决定，让正常审批继续。若多个匹配 Hook 给出决定，任何 deny 都优先。

它不会为原本无需审批的动作凭空创建审查，也不应替代命令规则和沙箱。返回不支持字段会失败关闭或被报告为错误，实施前应按当前事件输出结构验证。

七、PostToolUse 为什么不能撤销副作用

PostToolUse 在工具完成后运行，适合扫描补丁、检查测试输出、写日志或阻止不合格结果继续被模型使用。此时 shell 或文件修改已经发生，即使 Hook 返回 block，也不能撤销已产生的外部副作用。

因此破坏性操作必须在 PreToolUse、权限边界或外层流程中控制。PostToolUse 可以要求模型修正、触发失败反馈或记录结果，但不是事务回滚机制。

八、命令 Hook 与 MCP Tool Hook 怎样选择

命令 Hook 通过 stdin 接收 JSON，在本地执行脚本；MCP Tool Hook 调用已连接服务器上的结构化工具。后者适合补丁扫描、集中策略或审计服务，输入模板可以引用工具参数。

无论哪种形式，都要设置合理 timeout，验证服务身份，并限制输出。Hook 运行目录通常是会话 cwd，仓库脚本应从 Git 根定位，避免相对路径指向错误文件。

九、同步与异步 Hook 的取舍

同步 Hook 会让 Codex 等待结果，适合真正需要阻止、批准、改写或立即反馈的策略。设置 async 后可在后台运行，适合非关键日志和遥测，减少主流程延迟。

后台 Hook 不能阻止、批准或改写触发它的操作，完成结果会在下一个安全点交付；会话结束时，未完成任务可能被取消。关键校验不应仅放在异步 Hook。

十、并发、多来源与顺序风险

多个文件中的匹配 Hook 都会运行，同一事件下的多个命令 Hook 可能并发启动，一个 Hook 不能阻止另一个已经开始。这意味着不能依赖文件顺序构建先清理、后执行的隐式链条。

需要顺序一致性时，把步骤放进同一个受审计脚本或外部编排中。设计重复运行安全的日志和扫描，避免两个并发 Hook 同时写同一文件或重复发送通知。

十一、输出大小与敏感信息

模型可见的 Hook 输出有大小限制，过大的 additionalContext 可能被写入临时文件并只提供首尾预览。大量上下文会挤占模型窗口并降低效果，因此输出应结构化、短小且只包含决策所需内容。

不要在 Hook 输出、日志或临时溢出文件中返回密码、密钥、完整环境变量或用户私密数据。扫描脚本应优先返回文件位置、规则编号和脱敏摘要。

十二、上线前的验证清单

确认 Hook 来源可信；为每个事件准备正反测试；限制 matcher；设置 timeout；验证错误与非零退出码；测试子目录启动；检查并发写入；避免敏感输出；保留禁用和回退方法；升级 Codex 后重新测试。

更多 Codex 工作流可访问 https://gptupcn.com/codex/ 。Hooks 仍会持续演进，事件、字段和支持工具以当前官方文档与本机版本为准。生产策略还应由 CI、权限和监控共同承担。

结语

Codex Hooks 的价值是把检查点嵌入代理生命周期。先从只记录的 PostToolUse 或 SessionStart 开始，验证信任、匹配与输出，再逐步引入 PreToolUse 和 PermissionRequest，能降低自动化误拦截与越权风险。