事件与 Hook 语义

类型化生命周期钩子注册器和决策语义核心适用于每个钩子结果。是 Plugin SDK 概览 的一部分。

事件与生命周期¶

参见 插件钩子 了解示例、常见钩子名称和守卫语义。

钩子决策语义¶

before_install 是插件运行时生命周期钩子，而不是操作员安装策略界面。当允许/警告/阻止决策必须覆盖 CLI 和 Gateway 支持的安装或更新路径时，请使用 security.installPolicy。

• before_tool_call：返回 { block: true } 是终止性的。一旦任意处理器设置它，较低优先级的处理器将被跳过。
• before_tool_call：返回 { block: false } 被视为无决策（等同于省略 block），而不是覆盖。
• before_install：返回 { block: true } 是终止性的。一旦任意处理器设置它，较低优先级的处理器将被跳过。
• before_install：返回 { block: false } 被视为无决策（等同于省略 block），而不是覆盖。
• reply_dispatch：返回 { handled: true, ... } 是终止性的。一旦任意处理器声明分发，较低优先级的处理器和默认模型分发路径将被跳过。
• message_sending：返回 { cancel: true } 是终止性的。一旦任意处理器设置它，较低优先级的处理器将被跳过。
• message_sending：返回 { cancel: false } 被视为无决策（等同于省略 cancel），而不是覆盖。
• message_received：当需要入站线程/主题路由时，请使用类型化的 threadId 字段。将 metadata 保留给通道特定的附加信息。
• message_sending：在回退到通道特定的 metadata 之前，请使用类型化的 replyToId / threadId 路由字段。
• gateway_start：对于 Gateway 拥有的启动状态，请使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.()，而不是依赖内部 gateway:startup 钩子。此时 Cron 可能仍在加载。
• cron_reconciled：在启动或调度器重新加载后，重建完整的外部 cron 投影。它包含 reason 和有效的 enabled 状态（包括 enabled: false），而 ctx.getCron?.() 返回精确的已协调调度器。将 ctx.abortSignal 传入持久化投影工作；当该调度器快照被取代或 Gateway 关闭时，它会中止。
• cron_changed：观察 Gateway 拥有的 cron 生命周期变更。scheduled 和 removed 事件是提交后的协调提示，而不是有序的增量日志。当任务没有下一次唤醒时，scheduled 事件的 event.nextRunAtMs 不存在；removed 事件仍携带已删除任务的快照。

外部唤醒调度器应对 cron_changed 事件进行防抖或合并，然后从 cron_reconciled 最后捕获的调度器重新读取完整的持久化视图。不要从 cron_changed 上下文中采用调度器：来自旧调度器的分离提示可能与后续重新加载重叠。

将 cron_reconciled 用作在 Gateway 启动或调度器替换时加载持久化状态的完整快照触发器。它不会在仅插件热重载时重放。观察处理器并行运行，且即发即忘的分发可能重叠，因此消费者不得依赖事件完成顺序。保持 OpenClaw 作为到期检查和执行的权威来源。

对于具有持久化替换、重试/退避和干净关闭的单飞适配器，参见 安全外部 cron 投影。