异步 Hooks

给 Hook 加上后台模式,让日志、通知等不需要结果的操作不拖慢 Claude 的工作节奏

实战16 分钟

一、为什么需要选择

Hook 默认同步执行——Claude 等待 Hook 完成,读取退出码和输出,再决定下一步。这是合理的默认行为:阻断危险操作(退出码 2)、注入上下文信息、做权限决策,都需要 Claude 拿到 Hook 的结果。

但并非所有 Hook 都需要 Claude 等待。

选错的代价

场景错选同步错选异步
日志记录(写文件/发送远程 API)Claude 每次工具调用额外等待几十到几百毫秒,网络延迟时更明显无影响——日志写入不需要 Claude 知道结果
文件保护(阻止编辑 .env无影响——正确选择Hook 的退出码 2 被忽略,危险操作照常执行
上下文注入(向 Claude 补充信息)无影响——正确选择stdout 被忽略,Claude 拿不到注入的信息

选错同步:性能损失。选错异步:功能失效。两个方向的代价不对称——异步选错的后果严重得多。


二、限制与红线

异步 Hook 通过 "async": true 启用,仅 command 类型支持。启动后 Claude 立即继续,不等待结果。

核心限制:异步 Hook 的所有输出通道失效。

通道同步 Hook异步 Hook
退出码读取读取(0=放行, 2=阻断)忽略
stdout 解析解析 JSON 输出忽略
stderr 反馈退出码 2 时反馈给 Claude忽略
阻断操作支持不支持
注入上下文支持不支持
权限决策支持不支持

异步 Hook 是纯粹的"发射后不管"模式。脚本是否执行成功、输出了什么、退出码是几,Claude 一概不知。

输出交付时机:异步 Hook 的输出(如果有)在下一对话轮次才交付——但由于输出通道已失效,这个交付对 Claude 的行为没有实际影响。

硬约束——以下场景绝不能用异步

付费内容

继续阅读完整课程

购买后即可解锁全部 16 个功能模块、实战场景与深度配置。

¥199¥399
  • 30 分钟完成第一个真实任务
  • 实战场景 + 深度配置
  • 长期访问,持续更新