Hook 故障排查

诊断未被发现、不符合条件或未执行的 Hook。属于 Hooks 指南的一部分。

故障排查¶

Hook 未被发现¶

使用 openclaw hooks list --json 检查报告中的 workspaceDir 和 managedHooksDir。确认你正在检查预期的主机、配置档和代理。每个 Hook 都需要 HOOK.md 和一个受支持的处理程序文件；仅有一个元数据文件是不够的。集合位置会检查直接子项。显式额外路径或链接根本身可以是一个 Hook 或 pack。对于 pack，请验证 openclaw.hooks 是否直接列出了预期的 Hook 目录：嵌套的 pack 和集合不会被跟随，且被拒绝的条目不会导致未列出的子项被扫描。

在 Gateway 日志中检查重复名称和包含警告。工作区 Hook 无法覆盖捆绑或托管的 Hook。对于额外目录和链接 pack，请验证 Hook 发现 中描述的根布局。

Hook 不符合条件¶

openclaw hooks info my-hook
openclaw hooks list --verbose

检查 blockedReason、Gateway 的 PATH 上缺失的二进制文件、环境变量、配置路径和操作系统。工作区 Hook 在显式启用之前处于禁用状态。未声明事件的 Hook 无法加载。报告可能满足要求，但并不能证明其模块导入成功。

Hook 未执行¶

检查 hooks.internal.enabled、已配置名称的选择，以及该 Hook 的 hookKey 条目和 重新加载模式。ready 报告不会覆盖主开关或名称选择，也不意味着加载了另一个代理的工作区。

openclaw logs --follow

查找导入/导出错误、边界失败、未知事件警告或 Hook error [<type>:<action>]。再次触发确切的事件，并验证 Hook 特定的标记或产物。普通聊天文本不会触发 command:new；/stop 不会发送 Hook 回复；元数据订阅不会凭空创建自定义触发器。

如果标记出现但聊天回复未出现，请检查 回复投递 中的生产者和路由，而不仅仅是启用状态。对于 session-memory，请允许后台写入完成，并检查已解析的代理工作区，而不是假设默认工作区。