插件 SDK 事件和钩子语义

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

事件和生命周期

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

Hook 决策语义

before_model_resolve 可以与 providerOverride 和 modelOverride 一起返回 fallbacksOverride: string[]。显式列表取代了运行的后备链； [] 禁用模型回退。每个字段的第一个定义值按优先级降序排列获胜，注册顺序打破平局。请参见 本地模型路由。

before_install 是插件运行时生命周期挂钩，而不是操作员安装策略表面。当 allow/warn/block 决策必须涵盖 CLI 和网关支持的安装或更新路径时，请使用 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：当您需要入站 thread/topic 路由时，使用类型化的 threadId 字段。保留 metadata 以获取特定于频道的附加功能。
• message_sending：在回退到特定于通道的 metadata 之前，使用类型化的 replyToId / threadId 路由字段。
• gateway_start: 请使用 ctx.config、ctx.workspaceDir 和 ctx.getCron?.() 来获取 Gateway 拥有的启动状态，而不是依赖内部的 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 作为到期检查和执行的事实来源。

对于具有耐用更换、retry/backoff 和干净关闭功能的单飞行适配器，请参阅 Safe 外部 cron 投影。