Webhook 是将 OpenClaw 从'聊天助手'快速转变为'响应式系统'的最佳方式。无需等待主动发送消息，GitHub 可以在 PR 提交时通知 OpenClaw，Stripe 可以在支付失败时触发处理，n8n 也可以按计划调度任务。OpenClaw 会接收这些传入事件，将其转换为代理运行或轻量级唤醒操作，然后将结果路由回您实际使用的任何渠道。
本文重点介绍 OpenClaw 网关上的 HTTP Webhook。OpenClaw 中还有另一种机制，在部分文档中被称为'钩子'，那是网关内部的事件钩子，仅在本地生命周期事件触发时运行。它们很有用，但 Stripe 或 GitHub 与服务器通信的方式并非通过它们。
两种不同的'钩子'系统
OpenClaw 最终提出了两个听起来相似的概念，容易让人混淆：
- HTTP Webhook：外部服务调用的入站 HTTP 端点。
- 内部钩子：运行在网关进程内部的本地事件处理程序。
如果您要集成 GitHub、Gmail、Stripe 或家庭传感器，则需要使用 HTTP Webhook。如果您想要'每当新会话开始时写入一个小的内存文件'，则适合使用内部钩子。它们可以一起使用，但解决的是不同的问题。
OpenClaw 中的 HTTP Webhook 结构
最简单的实现方式是，OpenClaw 在网关上公开一个 webhook 路径，并使用共享密钥对其进行保护。外部服务向该路径发送 JSON POST 请求，OpenClaw 会将其转换为唤醒事件或完整的代理运行。
通常你会看到三种类型的端点：
- 一个类似'唤醒'的端点，仅轻轻通知代理。
- 一个'代理运行'风格的端点，可执行提示并向聊天频道发送回复。
- 您可以使用模板或转换将自定义名称的端点映射到上述端点之一。
即使不编写代码，映射也能帮你完成很多工作。如果需要编写代码，转换功能可以用来处理复杂的有效负载并过滤掉无关的事件类型。
在配置中启用 Webhook
Webhook 配置位于 hooks 代码块中。文件名会因安装方式而异，但原理相同：启用钩子、设置令牌并确定所需的 URL 路径。
以下是一个配置示例，请将其作为参考：
hooks: { enabled: true, path: "/hooks", token: "put-a-long-random-secret-here" }
该令牌就是您的 Webhook 密码。请勿重复使用其他地方的 API 密钥，也不要使用过短的密钥。如果您将 OpenClaw 作为服务运行，请将其放入环境变量中，而不是硬编码到会被复制的文件中。
Webhook 身份验证
大多数设置使用 Bearer 令牌标头，因为它几乎被所有 webhook 发送器和自动化平台所支持。请求如下所示：
Authorization: Bearer YOUR_HOOK_TOKEN
有些集成方案会使用自定义标头。如果连接的服务完全无法设置标头，则需要一个中间设备在转发之前添加标头。Hook 继电器和自动化工具非常适合这项工作。
实际使用的内置 Webhook 端点
即使构建了大量的自定义映射，大多数人最终还是会依赖两个核心行为：'唤醒'和'运行代理'。名称可能因安装环境而异，但行为是一致的。
唤醒终点
唤醒端点用于那些你不需要立即得到响应的事件。你只是希望代理注意到发生了某些事情。可以把它想象成轻轻拍拍肩膀。
适用于'传感器状态改变'或'作业完成'之类的事件，在这些场景中，工作流程已经完成了繁重的工作，OpenClaw 只需要决定该事件是否重要或如何对其进行总结。
最小有效载荷通常包含一个描述事件的文本字段。某些设置还支持一种模式，用于决定代理是立即唤醒还是等待下一次预定的心跳。
代理运行端点
代理运行端点用于需要实际执行操作的事件。例如，GitHub 发送拉取请求事件，而您希望 OpenClaw 汇总差异；Stripe 发送支付失败事件，而您希望向 Slack 发送一条消息以及一份简短的失败原因说明。
