跳转至

钩子参考

注册规则、执行契约、每个处理器的预算,以及完整的类型化钩子目录。属于 插件钩子 指南的一部分。

注册与执行

保持 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