OpenClaw Webhook 详解：完整指南
Webhook 是将 OpenClaw 从“聊天助手”快速转变为“响应式系统”的最佳方式。无需等待您主动发送消息，GitHub 可以在 PR 提交时通知 OpenClaw，Stripe 可以在支付失败时通知 OpenClaw，n8n 也可以按计划通知 OpenClaw。OpenClaw 会接收这些传入事件，并将其转换为代理运行或轻量级唤醒操作，然后将结果路由回您实际使用的任何渠道。
本文重点介绍 OpenClaw 网关上的 HTTP Webhook。OpenClaw 中还有另一种东西，在一些文档和配置中也被称为“钩子”。这些是网关内部的事件钩子，当本地生命周期事件触发时运行。它们也很有用，但 Stripe 或 GitHub 与服务器通信的方式并非通过它们。
如果您的 OpenClaw 实例是刚刚部署在 VPS 上，并且您仍然使用 SSH 进行基本操作，那么首先要确保网关稳定，这虽然有点枯燥。OpenClaw的 SSH 快速入门指南可以使这一步骤更加顺畅。
两种不同的“钩子”系统以及命名为何会让人困惑
OpenClaw最终提出了两个听起来很相似的概念：
- HTTP Webhook是外部服务调用的入站 HTTP 端点。
- 内部钩子是运行在网关进程内部的本地事件处理程序。
如果您要集成 GitHub、Gmail、Stripe 或家庭传感器，则需要使用 HTTP Webhook。如果您想要“每当新会话开始时写入一个小的内存文件”，则需要使用内部钩子。它们可以一起使用，但解决的是不同的问题。
OpenClaw 中的 HTTP Webhook 是什么样子的
最简单的实现方式是，OpenClaw 在网关上公开一个 webhook 路径，并使用共享密钥对其进行保护。外部服务向该路径发送 JSON POST 请求，OpenClaw 会将其转换为唤醒事件或完整的代理运行。
您通常会看到三种类型的端点：
- 一个类似“唤醒”的端点，它只是轻轻地通知代理。
- 一个“代理运行”风格的端点，可以执行提示并向聊天频道发送回复。
- 您可以使用模板或转换将自定义名称的端点映射到上述端点之一。
即使你从不编写代码，映射也能帮你完成很多工作。如果你确实需要编写代码，那么转换功能可以用来处理复杂的有效负载并过滤掉无关的事件类型。
在配置中启用 Webhook
Webhook 配置位于hooksOpenClaw 配置文件的一个代码块中。文件名会因安装方式而异，但原理相同：启用钩子、设置令牌并确定所需的 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/stripeStripe 的有效负载。
映射通常有两个作用：
- 将入站有效负载转换为您希望代理看到的消息。
- 决定如何处理结果，例如发布到 Slack 还是内部共享。
基于模板的映射
模板映射是一个很好的起点，因为它们易于阅读。您只需匹配一个路径，然后使用 JSON 正文中的几个字段构建消息即可。
hooks: { enabled: true, path: "/hooks", token: "${OPENCLAW_HOOKS_TOKEN}", 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，则跳过该事件。
一个重要的操作细节是这些转换文件的存放位置。将它们放在一个具有严格权限的专用目录中，并像对待代码一样对待它们，因为它们本质上就是代码。
如果你想经常进行这类扩展工作，技能和扩展模型至关重要。OpenClaw技能指南很有帮助，因为 webhook 和技能通常配合使用：webhook 唤醒代理，然后技能获取数据、执行实际操作并返回结果。
会话密钥和去重
Webhook 系统会重试。即使是最好的系统也会这样做。这不是漏洞。当服务器重启或网络丢包时，这是为了保持系统的可靠性。
你需要以下几种图案之一：
- 每个集成都使用固定的会话密钥，因此所有 GitHub 事件都会落入同一个“GitHub”会话中，您可以根据事件 ID 添加自己的去重功能。
- 每个实体对应一个会话密钥，例如每个拉取请求编号对应一个会话密钥，或者每个工单 ID 对应一个会话密钥。
这里存在安全隐患。允许调用者选择会话密钥听起来很方便，但攻击者也可能将数据散布到多个会话中，导致存储空间膨胀或历史记录混乱。如果您的配置支持将会话密钥限制为特定前缀，请启用此功能。如果您不需要调用者选择密钥，则不要启用它。
符合人们实际使用方式的真实示例
GitHub 拉取请求事件
GitHub 是一个经典的 webhook 源，因为它对 webhook 的支持非常完善，而且 payload 的文档也很齐全。一个典型的流程是：
- GitHub 发送拉取请求事件
- OpenClaw 通过映射的端点接收它
- OpenClaw 获取 PR 差异，然后写入摘要，并可选择性地添加注释。
对于 GitHub 而言，官方的 Webhook 文档至关重要，因为事件类型和有效负载字段都不能靠猜测。GitHub Webhook 文档
如果您想要了解“OpenClaw 连接到 GitHub 后会做什么”，请参阅此处的专门指南：OpenClaw GitHub 自动化，用于 PR 审查和 CI 监控。
网络爬虫警报和变更检测
Webhook 也使得网页抓取从一次性脚本变成了自动化操作。抓取程序会检查页面并存储结果，然后在页面内容发生变化时向 OpenClaw 发送一个 Webhook 消息。OpenClaw 会判断该消息是否重要，然后只发送一条消息，而不是二十条。
如果你使用 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 配置，请尽可能避免将原始网关端口直接暴露给互联网。如果需要外部访问，请通过代理隧道或尾网进行。有关VPS 上如何安全托管 OpenClaw 的一般托管指南，请参阅相关文档。
安全基础知识（切勿跳过）
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 决定发送什么消息以及发送到哪里。
这有助于保持代理上下文的清晰性。同时，也能避免您为从未关心过的事件支付模型代币。
