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 配置位于 hooks OpenClaw 配置文件的一个代码块中。文件名会因安装方式而异，但原理相同：启用钩子、设置令牌并确定所需的 URL 路径。
以下是一个配置示例。请将其作为参考，而非绝对标准。根据版本和安装方式的不同，您现有的配置项可能略有不同。
{
"hooks": {
"enabled": true,
"path": "/hooks",
"token": "put-a-long-random-secret-here"
}
}
该令牌就是您的 Webhook 密码。请勿重复使用其他地方的 API 密钥，也不要使用过短的密钥。如果您将 OpenClaw 作为服务运行，请将其放入环境变量中，而不是将其硬编码到会被复制的文件中。
Webhook 身份验证是如何发送的
大多数设置都使用 Bearer 令牌标头，因为它几乎被所有 webhook 发送器和自动化平台所支持。请求如下所示：
