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 发送一条消息以及一份简短的失败原因说明。
代理运行有效载荷通常包括：
- 提示或运行指令的消息
- 用于在日志或摘要中标记事件的名称
- 如果您希望将响应路由到特定位置，提供额外的渠道
一个实际细节：你需要幂等性。Webhook 发送者可以重试，中继可以重放。你不希望收到重复的'付款失败'提醒或重复的 PR 审核。你可以通过选择一个稳定的会话密钥，或者将'已处理事件 ID'存储在某个地方，然后跳过重复项来解决这个问题。
映射 Webhook 及其优势
映射 Webhook 让 OpenClaw 能够更好地进行实际集成。它不再强制每个发送方都匹配一个固定的有效负载，而是创建一个映射，使其 /hooks/github 能够同时理解 GitHub 和 /hooks/stripe 的有效负载。
映射通常有两个作用：
- 将入站有效负载转换为您希望代理看到的消息。
- 决定如何处理结果，例如发布到 Slack 还是内部共享。
基于模板的映射
模板映射是一个很好的起点，因为它们易于阅读。您只需匹配一个路径，然后使用 JSON 正文中的几个字段构建消息即可。
mappings: [
{
id: "github-push",
match: { path: "github-push" },
action: "agent",
name: "GitHub",
messageTemplate: "GitHub push to {{body.repository.full_name}} by {{body.pusher.name}}"
}
]
这个模板故意做得比较单调。在生产环境中，通常会添加过滤机制，只对关心的事件进行操作，并将响应路由到正确的位置。
转换模块以适应实际有效载荷
一旦需要逻辑，模板就不够用了。例如：只响应 PR 打开和 PR 更新事件，忽略'编辑'事件。或者将 payment_failed 路由到私有频道，而将 invoice_paid 路由到会计频道。这时，转换功能就派上用场了。
转换函数是一个小型 JavaScript 或 TypeScript 函数，它接收传入的请求体并返回一个规范化的 action 对象。如果转换函数返回 null，则跳过该事件。
一个重要的操作细节是这些转换文件的存放位置。将它们放在一个具有严格权限的专用目录中，并像对待代码一样对待它们，因为它们本质上就是代码。
如果你想经常进行这类扩展工作，技能和扩展模型至关重要。webhook 和技能通常配合使用：webhook 唤醒代理，然后技能获取数据、执行实际操作并返回结果。
会话密钥和去重
Webhook 系统会重试。即使是最好的系统也会这样做。这不是漏洞。当服务器重启或网络丢包时，这是为了保持系统的可靠性。
你需要以下几种模式之一：
- 每个集成都使用固定的会话密钥，因此所有 GitHub 事件都会落入同一个'GitHub'会话中，您可以根据事件 ID 添加自己的去重功能。
- 每个实体对应一个会话密钥，例如每个拉取请求编号对应一个会话密钥，或者每个工单 ID 对应一个会话密钥。
这里存在安全隐患。允许调用者选择会话密钥听起来很方便，但攻击者也可能将数据散布到多个会话中，导致存储空间膨胀或历史记录混乱。如果您的配置支持将会话密钥限制为特定前缀，请启用此功能。如果您不需要调用者选择密钥，则不要启用它。
真实场景示例
GitHub 拉取请求事件
GitHub 是一个经典的 webhook 源，因为它对 webhook 的支持非常完善，而且 payload 的文档也很齐全。一个典型的流程是：
- GitHub 发送拉取请求事件
- OpenClaw 通过映射的端点接收它
- OpenClaw 获取 PR 差异，然后写入摘要，并可选择性地添加注释。
对于 GitHub 而言，官方的 Webhook 文档至关重要，因为事件类型和有效负载字段都不能靠猜测。GitHub Webhook 文档
网络爬虫警报和变更检测
Webhook 也使得网页抓取从一次性脚本变成了自动化操作。抓取程序会检查页面并存储结果，然后在页面内容发生变化时向 OpenClaw 发送一个 Webhook 消息。OpenClaw 会判断该消息是否重要，然后只发送一条消息，而不是二十条。
如果你使用 OpenClaw 进行网页抓取，那么你的浏览器和网页抓取技能也可以成为工作流程的一部分。
Stripe 和支付
Stripe Webhook 是一个很好的例子，因为它在 Stripe 端内置了签名验证机制，并且事件类型系统非常清晰。如果您要处理计费事件，则不应仅仅依赖'共享令牌'。您需要在边缘验证 Stripe 的签名，然后再将其转发到 OpenClaw。
Stripe 的 Webhook 文档在这里，值得一读。Stripe Webhook 文档
n8n 和自动化平台
自动化平台就像是万能胶带层。OpenClaw 擅长推理和总结，然后选择下一步操作。n8n 则擅长保管调用 API 的凭证，并在不消耗模型代币的情况下执行繁琐的转换。
有两种常见模式：
- 模式 A：n8n 触发 OpenClaw。n8n 接收事件或按计划运行，然后调用 OpenClaw 代理端点，并发送类似'汇总新线索'或'此构建失败，请解析日志片段'的消息。
- 模式 B：OpenClaw 触发 n8n。OpenClaw 确定要执行的操作，然后调用 n8n webhook 来执行该操作。这是一种将密钥排除在代理运行时之外并保持集成简洁的好方法。
n8n 的 webhook 和 HTTP 请求节点使这一切变得非常简单。n8n webhook 节点文档
生产可靠性及原始 Webhook 的问题
实际问题是这样的：你的 webhook 发送方触发了一个事件，但你的网关正在重启。如果发送方不重试，或者重试时间很短，你就会丢失这个事件。这时人们就开始抱怨'webhook 不可靠'，而真正的问题是'我的端点没有队列'。
你可以通过以下几种方式来加强这一点：
方案一：使用存储并重试的 Webhook 中继
中继服务器位于 GitHub、Stripe 等服务商和您的 OpenClaw 端点之间。它们首先接收 webhook 请求，存储后再转发给您，并会进行重试。许多中继服务器还添加了去重功能和仪表盘，以便您可以重放失败的请求。
Hookdeck 是此类产品中的常见选择。
如果使用中继，还可以解决'某些服务无法设置标头'的问题，因为中继可以在转发端添加您的 Bearer 令牌标头。
方案二：反向代理加进程管理器
如果您不想使用中继，可以在网关前面部署反向代理。将其用于 TLS 终止的基本过滤和速率限制。在 systemd 或类似的监控程序下运行 OpenClaw，以便在发生故障后快速恢复。虽然这无法提供持久队列，但可以减少停机时间。
对于 VPS 配置，请尽可能避免将原始网关端口直接暴露给互联网。如果需要外部访问，请通过代理隧道或尾网进行。
安全基础知识
Webhook 端点会被扫描。这并非因为你有什么特殊之处，而是因为互联网的本质就是如此。请像对待密码一样对待你的 Webhook 令牌，并将传入的有效负载视为不可信的输入。
保持 Webhook 表面积小
- 使用长随机令牌
- 如果您的配置支持，则可以限制可以通过 webhook 调用联系的代理。
- 避免直接暴露网关，最好使用代理或专用网络。
必要时请核实提供商签名
共享令牌是一个不错的基准，但它不能替代提供商签名验证。GitHub、Stripe 等服务商可以对 webhook 请求进行签名。如果可以在边缘端验证签名，请在边缘端进行验证，然后将验证通过的事件转发到 OpenClaw。
谨慎使用'不安全内容'开关
某些配置允许绕过'可信内部来源'的安全封装。对于只有您内部系统才能调用的 webhook 来说，这没有问题。但请勿对公共 webhook 来源启用此功能。webhook 有效负载可能包含提示注入尝试，就像抓取的网页一样。
如果你要构建任何带有外部触发器的重要程序，请务必阅读一遍 OpenClaw 安全最佳实践。它涵盖了与 Webhook 相同的理念：最小权限和严格的隔离。
OpenClaw 内部钩子
内部钩子并非 HTTP 请求。它们是一些小型处理程序，会在网关内部发生 OpenClaw 事件时运行。人们使用它们来实现诸如写入审计日志、在会话重置时保存'会话摘要'、在启动时注入额外的引导文件或在网关启动时运行一个简短的 BOOT.md 例程等功能。
通常情况下，该结构包含一个文件夹，其中包含元数据文件和处理脚本。处理脚本接收事件对象，然后可以记录、修改或追加消息。这是一种无需添加完整插件即可进行本地自动化的好方法。
内部钩子也是实现'护栏日志记录'的好地方。例如：每当一个工具运行时，就向日志文件写入一条简短的记录，以便以后可以回答'代理昨天做了什么'。
可扩展的常见 Webhook 模式
单个入口端点加映射
您公开一个 webhook 基本路径，然后为每个服务添加映射。您的外部系统调用：
/hooks/github/hooks/stripe/hooks/ci/hooks/sensor
每个映射都会将请求转换为唤醒或代理运行。这样可以简化外部 URL，并将逻辑保留在 OpenClaw 内部，方便您进行更改而无需重新配置每个服务。
噪声事件源的两阶段处理
有些数据源噪声较大。持续集成 (CI) 系统每次运行可能会发送多个事件。监控系统可能会频繁发出警报。在这些情况下，两阶段设计效果很好：
第一阶段是 Webhook 接收器，它只负责过滤和去重，然后将干净的事件发布到 OpenClaw。第二阶段是 OpenClaw 决定发送什么消息以及发送到哪里。
这有助于保持代理上下文的清晰性。同时，也能避免您为从未关心过的事件支付模型代币。