钩子参考
注册规则、执行契约、每个处理器的预算,以及完整的类型化钩子目录。属于 插件钩子 指南的一部分。
注册与执行¶
保持 register(api) 为同步,并在那里注册处理器。处理器本身可以是异步的,但两个同步持久化钩子除外。
处理器默认优先级为 0;优先级较高的先运行,注册顺序用于打破平局。执行方式取决于钩子类型:
| 类型 | 执行契约 |
|---|---|
| Modify | 顺序执行;结果按照下文该钩子的契约合并。返回重写通常不会更改传递给后续处理器的 事件。 |
| Claim | 顺序执行;第一个 { handled: true } 获胜并跳过其余处理器。 |
| Gate | 顺序执行;阻止会停止其余处理器。 |
| Observe | 处理器并发运行;返回值被忽略。发射器可以等待完成,也可以以即发即弃方式派发。 |
| Sync modify/gate | 同步,按优先级顺序执行;每个处理器看到最新消息。Promise 会被忽略并产生警告。 |
| Evaluate | 技能评估器并发运行,并产生各自带归属的结果。 |
优先级不会串行化观察副作用。即发即弃事件可能与后续事件重叠,回调不是持久事件队列。请显式返回修改,而不是依赖就地变更。
api.on(name, handler, opts?) 接受:
| 选项 | 效果 |
|---|---|
matcher |
由 before_tool_call 或 after_tool_call 处理的非空规范 OpenClaw 工具 id 列表,例如 exec、apply_patch 或 spawn_agent。省略以匹配所有工具。空列表、通配符、空白以及特定于提供程序的别名无效。 |
priority |
排序;较高的先运行。 |
registrationId |
插件内一次注册的稳定标识。技能评估器将其用作 evaluatorId;否则使用插件 id。 |
timeoutMs |
每个处理器的异步等待预算。超时会应用下文该钩子的失败策略;它不会取消处理器或其副作用。省略以使用运行器的默认值(如果存在)。 |
eligibleTriggers |
仅用于 before_agent_reply,将主机派发限制为 cron、heartbeat 或 user 中的一个或多个。 |
eligibleDispatchKinds |
仅用于 reply_dispatch,将主机派发限制为 agent、acp 或两者。省略以处理所有派发类型。 |
requiresToolAuthority |
仅用于 before_prompt_build,在主机确定当前轮次的工具集后运行处理器,并提供临时 ctx.toolAuthority。对于必须遵循工具策略的上下文检索,请使用此选项。 |
触发器资格在主机调用处理器之前由主机强制执行。因此,以 eligibleTriggers: ["heartbeat", "cron"] 注册的钩子对用户轮次不活动,包括恢复的用户轮次。省略、空、格式错误或部分未知的列表仍不受限制,因此钩子会在这些轮次运行。其他钩子类型不接受此选项。
操作员可以在不修补插件代码的情况下设置钩子预算:
{
"plugins": {
"entries": {
"my-plugin": {
"hooks": {
"timeoutMs": 30000,
"timeouts": {
"before_prompt_build": 90000,
"agent_end": 60000
}
}
}
}
}
}
hooks.timeouts.<hookName> 覆盖 hooks.timeoutMs,后者覆盖插件编写的 api.on(..., { timeoutMs }) 值。这两个操作员配置字段接受最大为 600000 ms 的正整数。对于已知较慢的钩子,建议优先使用按钩子覆盖,以免某个插件在所有地方都获得更长的预算。
超时的处理器 Promise 会继续运行,因为钩子回调不会收到由超时拥有的取消信号。before_tool_call 可能会收到所属工具调用的 ctx.abortSignal,但钩子超时到期不会中止它。钩子派发可以在该插件工作仍在进行时释放其 Gateway 准入。拥有长时间运行工作的插件必须提供自己的取消和关闭生命周期。
Prompt 构建处理器可以使用 ctx.hookInvocation.assertActive() 在其结果不再符合条件后拒绝副作用。参见 处理器生命周期。
标准运行器按每个处理器应用以下默认值:
| 钩子 | 默认超时 | 抛出错误或超时时 |
|---|---|---|
before_agent_run, before_tool_call, before_install |
15 秒 | 失败关闭:阻止运行、工具调用或安装 |
before_agent_finalize, before_prompt_build, message_sending, reply_payload_sending, resolve_exec_env |
15 秒 | 记录日志并跳过失败的处理器;保留其他成功结果 |
agent_end, before_compaction, after_compaction, skill_changed |
30 秒 | 记录日志并继续 |
channel_pairing_requested |
2 秒 | 记录日志并继续 |
gateway_stop |
5 秒 | 记录日志并继续关闭 |
| 其他异步钩子,包括认领钩子 | 除非已配置,否则无运行器超时 | 记录日志并继续 |
tool_result_persist, before_message_write |
无异步超时 | 同步错误会被记录;失败的结果会被忽略 |
发射器可以施加更严格的整体生命周期预算,例如下文关闭时的
session_end 排空。超时仅限制异步
await;它无法中断同步 JavaScript。对于策略要求,
请使用失败关闭的门控,而不是假设观察或投递钩子
在失败时会拒绝该操作。
对于认领钩子,继续意味着尝试下一个处理器。调用方决定
如果没有人认领时会发生什么;对于已绑定会话,失败的 inbound_claim 可以产生绑定通知,而不是普通代理回复。
使用 createReplyDispatcher 的通道插件同样可以声明更大的
正数每阶段预算,使用 beforeDeliverOptions: { timeoutMs },或者在
使用 dispatcher.appendBeforeDeliver(handler, { timeoutMs }) 追加工作时声明。
如果没有所有者声明的预算,这些回调将使用相同的 15 秒
默认值,因此挂起的回调无法占用串行化投递通道。
钩子目录¶
钩子按它们扩展的界面分组。类型指向上文所述的执行 契约;修改型钩子不是观察型钩子。
代理轮次
| 钩子 | 类型 | 用途 |
|---|---|---|
before_model_resolve |
修改 | 在会话消息加载之前覆盖提供商或模型 |
agent_turn_prepare |
修改 | 检查已排空的插件轮次注入,并在 Prompt 钩子之前添加上下文 |
before_prompt_build |
修改 | 添加 Prompt 上下文,缩小当前轮次已提交工具的范围,或执行已授权的后置策略增强 |
before_agent_run |
门控 | 在模型提交前检查 Prompt 和会话消息;节点轮次在 worker 本地上下文组装前对 Gateway 输入进行门控 |
before_agent_reply |
认领 | 使用合成回复或静默短路模型轮次 |
before_agent_finalize |
修改 | 检查自然最终答案并请求再进行一次模型处理 |
agent_end |
观察 | 观察最终消息、成功状态和运行时长 |
heartbeat_prompt_contribution |
修改 | 为后台监控和生命周期插件添加仅用于心跳的上下文 |
会话观察
| 钩子 | 类型 | 用途 |
|---|---|---|
model_call_started / model_call_ended |
观察 | 已净化的提供商/模型调用元数据:计时、结果、有界的 request-id 哈希。不包含 Prompt 或响应内容。 |
llm_input |
观察 | 提供商输入:系统 Prompt、Prompt、历史 |
llm_output |
观察 | 提供商输出、使用情况,以及可用时已解析的 contextTokenBudget |
| 钩子 | 类型 | 用途 |
|---|---|---|
工具
| 钩子 | 类型 | 用途 |
|---|---|---|
before_tool_call |
修改 / 门控 | 重写工具参数、阻止执行,或要求审批 |
after_tool_call |
观察 | 观察工具结果、错误和持续时间 |
resolve_exec_env |
修改 | 为 exec 提供插件拥有的环境变量 |
tool_result_persist |
同步修改 | 在转录持久化之前重写 toolResult 消息 |
before_message_write |
同步修改 / 门控 | 在转录持久化之前重写或阻止消息 |
消息与投递
| 钩子 | 类型 | 用途 |
|---|---|---|
inbound_claim |
认领 | 认领入站消息,供拥有其会话绑定的插件处理 |
channel_pairing_requested |
观察 | 观察新创建的 DM 配对请求 |
message_received |
观察 | 观察入站内容、发送者、线程和元数据 |
message_sending |
修改 / 门控 | 重写出站内容或取消投递 |
reply_payload_sending |
修改 / 门控 | 在投递前修改或取消规范化回复负载 |
message_sent |
观察 | 观察出站投递成功或失败 |
before_dispatch |
认领 | 在正常模型分发之前处理入站消息 |
reply_dispatch |
认领 | 接管回复生成与分发,替代默认模型路径 |
inbound_claim 不是全局预路由广播。OpenClaw 仅针对拥有该消息核心管理的会话绑定的插件调用它。若要在模型输入之前抑制普通智能体轮次,且不在转录中保留原始提示,请在受支持的 runner 上使用 before_agent_run。若要以合成回复或静默短路智能体轮次,请使用 before_agent_reply。
对于心跳轮次,当宿主知道底层系统事件队列时,before_agent_reply 会接收 ctx.heartbeatEventQueueSessionKey。对于隔离的心跳运行,该值可能与 ctx.sessionKey 不同。请使用提供的键进行事件查找;不要通过移除 :heartbeat 后缀来推导基础会话,因为配置的会话可能名为 heartbeat。该字段对旧版宿主是可选的。没有它时,插件只能检查 ctx.sessionKey;它们无法推断隔离运行的基础队列。该字段仅标识一个已存在的队列,并不授予额外访问权限。
会话与压缩
| 钩子 | 类型 | 用途 |
|---|---|---|
session_start / session_end |
观察 | 跟踪会话生命周期边界 |
before_compaction / after_compaction |
观察 | 观察压缩边界;不重写或否决结果 |
before_reset |
观察 | 观察会话重置事件(/reset、编程式重置) |
成功的引擎拥有的压缩尝试即使没有历史变更,也会发出 after_compaction,且 compactedCount: 0。失败或中止的尝试不会发出该完成钩子。
session_end.reason 是 new、reset、idle、daily、compaction、deleted、shutdown、restart 或 unknown 之一。session_start 没有 reason 字段;它可以包含 resumedFrom。关闭/重启事件来自活动会话的 Gateway 终结器,因此插件可以在进程退出前关闭会话状态。
在当前宿主上,session_end 上下文包含 endedTranscript。拥有会话访问权限的插件在 OpenClaw 拥有不可变的已结束会话源时,会收到 { available: true, readTail }。调用必须提供正的 maxMessages 和 maxBytes;OpenClaw 会强制宿主上限并返回 { messages, totalMessages, truncated }。只要已准入的处理程序处于活动状态,读取器就保持有效。在处理程序完成、其配置的钩子超时、强制退役其所属插件实例,或关闭/重启排空期限之后,保留的或仍在等待的读取会被拒绝。
当不存在安全源时,该值为 { available: false, reason }。当前原因可区分缺少会话权限、没有稳定截止点的生命周期、已删除的隐身状态、不可用的存档以及不受支持的源。这是一个明确的非结果,而不是空转录。针对此契约编译的插件仍应将缺失字段视为旧版宿主。
session_end 本身仍然是元数据钩子,可以在没有会话访问权限的情况下注册。对于非捆绑插件,plugins.entries.<id>.hooks.allowConversationAccess=true 仅授予有界的已结束转录读取器。捆绑插件遵循相同的有效策略,并可通过 allowConversationAccess: false 被拒绝。权限变更适用于由成功发布的插件运行时替换所准入的处理程序。已在运行的处理程序在其有界调用保持准入期间,保留其所属代际的授权;处理程序完成、钩子超时、强制实例退役或关闭排空超时会结束该租约。前驱排空和后继发布可能重叠。
关闭和重启在所有活动会话和插件处理器之间共享一个 总计 2 秒的 session_end 排空预算;该预算不是按处理器划分的。请快速返回,或确保最终化有界且持久化崩溃一致。如果预算到期,OpenClaw 会记录 shutdown session-end drain timed out 并继续关闭,因此未完成的插件工作可能会被中断。
对于带有 parentSessionKey 和 emitCommandHooks: true 的 sessions.create 调用,独立的子会话始终会接收 session_start。调用方通过 succeedsParent 声明父会话是否也会接收终止的 session_end:true 表示后继者,false 表示并行子会话。省略该字段会保留传统的父会话滚动行为。在这两种情况下,command:new 和 before_reset 钩子仍然描述所请求的 /new 操作。
子代理
subagent_spawned/subagent_ended- 观察子代理启动和完成。subagent_progress- 观察后台子运行的可移植started/ended进度;包括runId、childSessionKey、可选的请求方路由,以及在ended时的结果。subagent_delivery_target- 当核心会话绑定无法投影路由时,用于完成投递的修改型兼容性钩子。第一个返回的origin生效。subagent_spawned在 OpenClaw 于启动前解析子会话的原生模型时,会包含resolvedModel和resolvedProvider。subagent_ended携带targetSessionKey(身份标识 - 与subagent_spawned.childSessionKey匹配)、targetKind("subagent"或"acp")、reason、可选的outcome("ok"、"error"、"timeout"、"killed"、"reset"或"deleted")、可选的error、runId、endedAt、accountId和sendFarewell。它不包含agentId或childSessionKey;请使用targetSessionKey与对应的subagent_spawned事件进行关联。
生命周期
| 钩子 | 类型 | 目的 |
|---|---|---|
gateway_start / gateway_stop |
观察 | 与 Gateway 一起启动或停止插件拥有的服务 |
cron_reconciled |
观察 | 在启动或重新加载后,对照完整的 Gateway cron 状态进行协调 |
cron_changed |
观察 | 观察 Gateway 拥有的 cron 生命周期变更(添加、更新、移除、启动、完成、计划) |
before_install |
修改 / 门控 | 检查来自已加载插件运行时的暂存技能或插件安装材料 |
skill_changed |
观察 | 观察已提交的实时技能创建、更新和移除事件 |
技能生命周期¶
skill_changed 在实时技能创建、更新或移除提交后触发,并包含可选的前后制品(含内容和树哈希),以及在可用时包含声明版本和源版本。
频道配对请求¶
当插件需要在未配对的 DM 发送方创建待处理配对请求后通知操作员或写入审计记录时,请使用 channel_pairing_requested。该钩子在请求创建时分发;配对回复的频道投递不会因缓慢或失败的钩子处理器而延迟。
api.on("channel_pairing_requested", async (event) => {
await notifyOperator({
text: `New ${event.channel} pairing request from ${event.senderId}: ${event.code}`,
});
});
该钩子仅用于观察。它不会批准、拒绝、抑制或重写配对回复。负载包含频道、可选的 accountId、频道范围内的 senderId、配对 code 以及频道元数据。请将配对代码视为实时的单次使用批准凭证,并仅将其交付给受信任的操作员接收端。请将 metadata 视为不可信的发送方提供的身份文本。该钩子不包含入站消息正文或媒体。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw