跳转至

插件钩子

插件钩子允许原生 OpenClaw 插件观察或更改代理运行、工具调用、消息投递和生命周期事件。使用 api.on("hook_name", handler) 注册类型化处理器,并返回该钩子文档中说明的结果。

有三种不同的钩子系统:

你想…… 使用
更改提示、控制工具、自定义回复或集成插件生命周期 本页的类型化插件钩子:api.on("before_tool_call", ...)
为 /new、/reset、/stop 或引导事件运行操作员安装的脚本 内部钩子:HOOK.md 以及冒号事件名称,例如 command:new 或 agent:bootstrap
通过 HTTP 从外部服务触发代理 Webhooks:Gateway HTTP 端点

插件还可以使用 api.registerHook(...) 注册内部钩子。这不是类型化 API:在那里注册下划线名称(例如 before_tool_call)会产生警告,并且类型化运行器永远不会调用该注册。对于 钩子目录 中的每个钩子,请使用 api.on(...)。

快速开始

本示例在不调用模型的情况下,回复包含 hook-demo-check 的用户消息。 它假设你已经有一个可用的 Gateway,并且可以向其发送普通聊天消息。有关包元数据、发布和安装选项,请参阅 构建插件 和 插件清单。

创建一个本地 hook-demo 目录,包含以下文件:

```json package.json { "name": "hook-demo", "version": "1.0.0", "type": "module", "openclaw": { "extensions": ["./index.ts"] } }

```json openclaw.plugin.json
{
  "id": "hook-demo",
  "name": "Hook Demo",
  "activation": { "onStartup": true },
  "configSchema": { "type": "object", "additionalProperties": false }
}

```typescript index.ts import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({ id: "hook-demo", name: "Hook Demo", description: "Reply to a hook check without a model call.", register(api) { api.on( "before_agent_reply", (event) => { if (event.cleanedBody.includes("hook-demo-check")) { return { handled: true, reply: { text: "Hook is working." } }; } }, { eligibleTriggers: ["user"] }, ); }, });

在加载本地插件代码之前,请先审查它:原生插件在 Gateway
进程中运行。链接并启用该目录(`--force` 表示确认从本地源安装):

```bash
openclaw plugins install --link ./hook-demo --force
openclaw plugins enable hook-demo

在 openclaw.json 中授予此插件访问会话钩子的权限:

{
  "plugins": {
    "entries": {
      "hook-demo": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true }
      }
    }
  }
}

将该条目合并到现有配置中,然后让默认的混合重载模式 应用它并进行检查:

openclaw plugins inspect hook-demo --runtime --json

将 hook-demo-check 作为普通聊天消息发送。预期结果为 Hook is working.;其他 消息继续通过正常代理路径处理。如果钩子未运行,请参阅 故障排除。

尽管名为 cleanedBody,但它实际上是准备好的运行提示,并且可能包含 通道上下文。示例匹配一个独特的标记,而不是假设该字段仅包含发送者的原始文本。

权限与作用范围

钩子注册不会绕过插件加载规则。插件必须已加载并启用;plugins.enabled、plugins.allow 和 plugins.deny 仍然 适用。更改插件代码后,运行 openclaw plugins reload <id>。在默认的混合重载模式下,钩子策略更改会热重载现有插件运行时。

  • 非捆绑插件需要显式设置 plugins.entries.<id>.hooks.allowConversationAccess: true,才能使用 before_model_resolve、agent_turn_prepare、before_prompt_build、 before_agent_reply、llm_input、llm_output、before_agent_finalize、 agent_end 和 before_agent_run。除非该选项显式为 false,否则捆绑插件被允许。
  • session_end 在没有该授权的情况下仍可作为仅元数据生命周期钩子使用。其有界的 ctx.endedTranscript 读取器仅在 有效的会话访问策略允许时可用;请参阅 会话生命周期契约。
  • allowPromptInjection: false 会阻止 agent_turn_prepare、 before_prompt_build、heartbeat_prompt_contribution 以及持久化的下一轮注入。它默认允许,但不会授予会话访问权限。 因此,前两个钩子需要这两种权限。
  • 这些是特定的注册门控,而不是沙箱,也不是针对每个可查看消息数据的钩子的通用过滤器。只安装你信任的插件。

隐身会话不会分发 llm_input 或 llm_output 观察。它们的 agent_end 钩子仍会接收运行标识、成功状态和持续时间,用于 清理和结算,但会接收空的 messages 且没有 error 文本。策略、提供商、审批以及显式调用的工具钩子仍然处于活动状态。 此边界不会沙箱化插件,也不会禁用原生 harness 遥测。

类型化处理器接收 (event, ctx)。事件描述操作;第二个参数携带钩子特定的上下文。诸如 ctx.agentId、ctx.sessionKey 和 ctx.runId 等字段在许多钩子中是可选的,并且在发出路径中可能缺失。注册不会自动 限定到单个代理或会话:必要时请在处理器中检查上下文。

在注册闭包内,从 api.pluginConfig 读取插件的已解析设置。类型化钩子不会收到通用的 event.context.pluginConfig 字段;该字段属于内部 api.registerHook(...) 事件契约。默认情况下,在混合重载模式中,编辑 plugins.entries.<id>.config 会替换插件实例,并使用新设置重新运行注册。

选择钩子

任务 钩子
在不进行模型调用的情况下回复 before_agent_reply → { handled: true, reply };省略 reply 表示静默
为一轮添加上下文或缩小工具范围 before_prompt_build
在受支持的 runner 上控制模型输入 before_agent_run → { outcome: "block", reason, message? }
阻止工具或请求审批 before_tool_call
重写完整出站回复(包括媒体) reply_payload_sending
重写出站文本或取消发送 message_sending
在不获取原始对话文本的情况下收集模型计时 model_call_started / model_call_ended
在一轮结束后或关闭时刷新状态 agent_end / gateway_stop

目录是注册 API,并不保证每个运行时都会发出每个钩子。例如,before_agent_run 由嵌入式和 CLI runner 实现,并由 Gateway 准入用于 OpenClaw 节点 worker 轮次。节点准入会在持久化用户消息或启动 worker 之前,提供 Gateway 的触发 Prompt 和已加载历史。阻止和钩子失败只会持久化已脱敏的阻止消息。节点准入会省略 systemPrompt:节点随后会组装其 bootstrap 和技能上下文。需要该最终上下文的策略必须使用受支持的本地 runner。不要依赖此钩子作为 Codex 或 Copilot 的输入门控。原生工具、转录和压缩边界也不同。参见 Codex 钩子边界 和 Agent harness 插件。

故障排查

症状 检查
插件已加载,但处理程序从未运行 对类型化名称使用 api.on,检查 openclaw plugins inspect <id> --runtime --json,并查看诊断信息中是否有被阻止的注册。运行时检查会在检查进程中加载插件;代码更改后使用 openclaw plugins reload <id>。
对话钩子被阻止 设置 plugins.entries.<id>.hooks.allowConversationAccess: true;对于 Prompt 钩子,还需检查 allowPromptInjection 不是 false。这些键属于 hooks,而不是插件的 config。
钩子仅对一个运行时或触发器有效 检查运行时边界和 eligibleTriggers。缺少上下文字段并不能证明发送者、agent 或授权状态不同。
持久化重写没有效果 同步返回 { message }。async 处理程序的结果会被忽略。
超时的钩子仍会执行工作 超时结束的是宿主的 await,而不是插件工作。请通过 I/O 传递可用的 abort 信号,并自行限制插件拥有的工作。
某个插件的重写消失 检查钩子的合并规则和优先级。message_sending 使用最后返回的内容;reply_payload_sending 会将每个更新后的 payload 继续传递。

即将弃用

一些与钩子相关的接口已弃用但仍受支持。移除资格在插件兼容性注册表中按接口跟踪,作为 removeAfter 日期或显式移除门控,而不是在主要版本边界处。请立即迁移:

  • 明文通道信封(在 inbound_claim 和 message_received 处理程序中)。优先使用类型化字段,而不是解析扁平信封文本:inbound_claim 暴露 event.bodyForAgent;message_received 暴露 event.content 和结构化元数据,而不是 BodyForAgent 字段。参见 明文通道信封 → BodyForAgent。
  • before_tool_call 中的 onResolution 现在使用类型化的 PluginApprovalResolution 联合类型(allow-once / allow-always / deny / timeout / cancelled),而不是自由格式的 string。
  • api.registerSessionExtension / api.enqueueNextTurnInjection 仍保留为顶层兼容性别名。新插件应使用 api.session.state.registerSessionExtension(...) 和 api.session.workflow.enqueueNextTurnInjection(...)。

完整列表包括内存能力注册、提供商思考配置文件、外部身份验证提供商、提供商发现类型、任务运行时访问器,以及 command-auth → command-status 重命名,请参阅 插件 SDK 迁移 → 当前弃用项。

每个章节迁移到了哪里

单页版本中的每个章节现在都位于此页面或以下五个子页面之一。单页版本中的锚点仍会解析到此处。

钩子参考

钩子参考 — 注册规则、执行契约、每个处理器的预算,以及完整的类型化钩子目录。

工具调用策略钩子

工具调用策略钩子 — 参数重写、阻止、审批、Exec 环境贡献和转录持久化。

Prompt 与会话钩子

Prompt 与会话钩子 — 模型解析、Prompt 构造、最终化,以及持久的、由插件拥有的会话状态。

消息与投递钩子

消息与投递钩子 — 入站拦截、回复接管和出站投递策略。

Gateway 与安装生命周期钩子

Gateway 与安装生命周期钩子 — 安装时检查、Gateway 服务生命周期,以及安全的外部 cron 投影。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw