本页内容
本页内容
自动化
钩子
钩子
内部挂钩是小型 JavaScript 或 TypeScript 处理程序,当 OpenClaw 发出事件时,它们在网关进程中运行。使用它们来保存会话上下文、记录重置命令或在消息和会话生命周期事件期间执行短暂的副作用。 OpenClaw 包括用于常见任务的 捆绑挂钩 ;您不需要编写插件来使用它们。
选择合适的扩展面
| 你想要… | 用途 |
|---|---|
在 /new 上保存上下文、记录命令或对会话和消息事件做出反应 |
内部挂钩(HOOK.md加上处理程序),在此描述 |
| 修改提示、拦截工具、控制回复或使用具有优先级和返回值的生命周期契约 | **插件挂钩**直通api.on(...) |
| 让另一个服务通过 HTTP 请求开始工作 | Webhooks |
| 导出遥测数据而不是改变行为 | 诊断事件 |
这些是独立的系统。 hooks.internal 配置该页面的事件处理程序; hooks.enabled 配置 HTTP 入口。内部事件名称(例如 message:received)不是键入的插件名称(例如 message_received)。
快速开始
从 command-logger 开始:它不需要额外的二进制文件或模型调用,并为您提供一个具体的文件来检查。在 Gateway 主机 上运行以下命令,并使用与该网关相同的配置文件和配置:
默认的 hybrid 重载模式 应用钩子配置更改而无需重新启动。使用重新加载模式 off,运行 openclaw gateway restart,或自行重新启动前台网关。当您的配置具有多个代理且没有隐式所有者时,请添加 --agent <id>。
在对话中,您可以安全地重置、以授权用户身份发送 /new 或 /reset。然后检查网关主机上的日志:
查找带有 "action":"new" 或 "action":"reset" 的新 JSON 行,最近的 timestamp,并且该对话是 sessionKey。对于自定义状态目录,请改为阅读 <stateDir>/logs/commands.log。这证明处理程序运行了;仅 openclaw hooks check 则不会。
该日志包含会话和发件人标识符。如果您不想保留这些记录,请在尝试后禁用该挂钩:
E合格、已启用并已加载
将这三项检查分开:
- 满足的要求:挂钩的OS、二进制文件、环境和配置要求在执行检查的主机上传递。
- 由config启用:每个hook/source策略允许它。工作区挂钩需要明确的选择加入;当启用广泛发现时,捆绑和托管挂钩不需要每个挂钩标志。
- Loaded:正在运行的网关选择了挂钩,导入了其处理程序,并注册了其事件。这还需要主交换机和配置的名称选择来允许它。
CLI 的 ready、eligible 和 loadable 字段描述前两个检查以及非空事件列表。他们确实 not 证明网关导入了处理程序,全局选择包含它,或者它的事件已触发。更改后,检查实际的副作用或特定于钩子的日志。
配置重新加载会先准备选定的处理程序,然后再将它们替换在一起。如果选定的处理程序无法加载,则先前的处理程序将保持活动状态。已经运行的事件以其原始处理程序结束;后续事件将使用新选择。重新加载不会重播 gateway:startup。
本地、远程和代理范围
hooks list、info 和 check 请求所选网关的库存。隐式本地网关在不可用或缺少报告方法时可以回退到本地发现。配置的远程网关或显式 OPENCLAW_GATEWAY_URL 不会在出现故障时回退到笔记本电脑的挂钩。
hooks enable 和 hooks disable 始终检查和修改 本地配置。他们不会通过 RPC 更新远程网关。在网关主机上运行它们以更改该主机的挂钩。
--agent <id> 选择要检查的工作区,而不是独立的挂钩注册表。保存的 hooks.internal.entries.<hookKey> 条目是全局的。网关将目录挂钩从其选定的工作空间加载到进程范围的注册表中;它不会仅仅因为您检查了每个代理的 hooks/ 目录而加载它。当加载的处理程序只应作用于特定代理时,它必须过滤事件的代理或会话。参见查找。
插件钩子
插件管理的内部挂钩在 hooks list 中显示为 plugin:<id>。它们参与此事件系统,但您启用或禁用所属插件,而不是使用 hooks enable 或 hooks disable 切换它们。目录加载器的配置名称选择不是类型 api.on 挂钩的策略门,也不是插件激活的替代品。
旧版 api.registerHook API 注册内部事件。它不会调用类型化的生命周期名称,例如 before_tool_call、message_received 或 session_start;注册这些名称会发出警告,将作者引导至 api.on(...)。对于需要类型化生命周期控制的新集成,请使用 Plugin hooks 参考。
最佳实践
一个事件的处理程序按顺序运行:首先是系列侦听器,然后是精确侦听器,按照每个组中的注册顺序。调度程序等待每个处理程序,捕获并记录抛出的错误,然后继续处理后面的处理程序。目录挂钩没有优先级选项。
此排序不会将不同的事件序列化。消息通知、补丁通知和自动重置工作可以与其他事件和代理处理重叠。没有一般的处理程序超时、取消信号、持久事件队列、自动重试或一次性保证。重新启动或进程退出可能会丢失正在进行的工作。
保持副作用简短且有限。等待属于处理程序的工作,设置网络调用超时,限制数据大小,并设计可重复操作,以便重试不会重复其效果。不要使用 void doHeavyWork(event) 作为通用解决方案:该工作会逃脱处理程序的 wait/error 边界,并且可能比其会话或进程的寿命更长。如果工作需要持久的工作生命周期,请使用拥有它的自动化或服务。
尽早过滤不相关的事件,并避免记录消息正文、整个配置对象或凭据。消息和会话数据可以是私有的。仅保留副作用所需的最低限度、保护输出文件并设置保留。长寿命定时器、观察者、套接字和客户端属于具有显式关闭生命周期的插件服务,而不是 request/event 处理程序。
CLI 参考
请参阅 openclaw hooks 了解每个公共报告和切换选项、JSON 输出字段、退出行为和 install/update 别名。
详细主题
这些页面包含用于遵循此页面上的快速入门的参考和操作材料。
| 页面 | 读它的时候 |
|---|---|
| 书写钩 | 您正在编写一个挂钩,并且需要文件布局、处理程序契约或 HOOK.md 字段。 |
| 查看配置与发现 | 您正在启用挂钩、缩小选择范围或跨源跟踪发现。 |
| 捆绑挂钩 | 您想要一个已发布的钩子并且需要它的行为、选项和检查。 |
| 查看事件类型和上下文 | 您需要事件键的触发器、等待行为或上下文字段。 |
| 故障排除 | 钩子未发现、不合格或未执行。 |
各部分移动的地方
先前单页版本的每个部分标题都保留其锚点,因此现有链接(例如 /automation/hooks#session-memory)仍然可以解析。每个条目都指向现在保存内容的页面。
- 书写挂钩
- H钩结构
- Handler实现
- 回复发货
- HOOK.md 格式
- 配置
- H钩发现
- H钩包
- 捆绑挂钩
- boot-md
- boot-md 详细信息
- bootstrap-extra-files
- 引导额外文件配置
- 命令记录器
- 命令记录器详细信息
- 压缩通知器
- 压缩通知程序详细信息
- 会话内存
- 会话内存详细信息
- 事件类型
- 事件背景亮点
- 消息上下文
- 故障排除
- H未发现
- H不符合条件
- H不执行