功能介绍

Webhook用于接收外部系统主动发送的HTTP请求，并把请求中的任务交给指定智能体处理。配置完成后，监控告警、订单变化、代码仓库事件或邮件通知等外部事件，可以在发生时触发PlugClaw进行分析、生成结果或调用已有工具，不需要先由用户打开对话并手动发送消息。

在这个过程中，外部系统是请求发送方，PlugClaw网关（Gateway）提供Webhook接收地址，allowedAgentIds中允许的智能体负责处理任务。Webhook只负责把事件送进PlugClaw；智能体最终能执行哪些操作，仍取决于它已有的模型、技能、工具和权限。

不同外部系统的事件格式、认证方式和重试规则可能不同。本文先使用本机测试请求触发main智能体，确认Webhook接收、Token认证和任务触发功能正常。真正接入第三方系统时，还需要根据对方的官方Webhook说明调整请求内容，并准备一个对方能够访问的地址。

Webhook地址和Token属于服务入口和访问凭证。不要在公开页面、对话或截图中暴露真实Token，也不要把Webhook开放给不受信任的调用方。需要通过外部网络访问时，应同时考虑HTTPS、网络访问限制和凭证保管，不能只把本机示例地址原样提供给外部系统。

配置前准备

开始前需要确认以下内容：

发送方        哪个外部系统会调用Webhook
目标智能体    收到请求后由哪个智能体处理，本文使用main
访问地址      发送方能够访问的PlugClaw网关地址
认证Token     用于验证请求来源的随机字符串
请求内容      外部事件如何转换为智能体能够理解的message

如果要使用main以外的智能体，需要先创建对应智能体，并确认它的智能体ID。智能体的创建和使用方式可参考《智能体管理》。

Webhook配置保存在openclaw.json中。修改前先备份原文件，后面的示例需要合并到现有配置中，不要覆盖文件中已有的模型、技能、频道或其他设置。

生成Webhook Token

在PlugOS设备的终端中运行以下命令，生成一段随机Token：

openssl rand -hex 32

复制命令返回的随机字符串并妥善保存。它相当于Webhook的访问密码，后续需要同时填写到PlugClaw配置和外部系统的请求中。Webhook Token应单独生成，不要与网关令牌、网关密码或其他服务凭证共用。

如果终端提示openssl不存在，不要改用简单密码代替，应通过当前运行环境中可信的随机凭证生成工具取得足够长的随机Token。

添加Webhook配置

打开openclaw.json，把下面的hooks配置合并到现有内容中，并将YOUR_HOOK_TOKEN替换为刚刚生成的真实Token：

{
  "hooks": {
    "enabled": true,
    "path": "/hooks",
    "token": "YOUR_HOOK_TOKEN",
    "allowedAgentIds": [
      "main"
    ],
    "allowRequestSessionKey": false
  }
}

各配置项的作用如下：

enabled                  是否启用Webhook接收功能
path                     Webhook地址在网关中的路径前缀
token                    调用方请求时必须提供的认证Token
allowedAgentIds          允许通过Webhook触发的智能体ID列表
allowRequestSessionKey   是否允许调用方自行指定会话标识

示例只允许触发main智能体，并且不允许请求方自行指定会话标识。没有明确的会话复用需求时，保持allowRequestSessionKey为false，可以减少外部请求进入非预期会话的风险。

保存配置后重启网关，让网关重新加载Webhook设置。具体操作可参考《网关管理》。网关无法正常启动时，先恢复修改前的openclaw.json备份，并检查JSON格式和Token引号是否完整。

发送本机测试请求

先在运行网关的PlugOS设备上进行本机测试，可以把网络访问问题与Webhook配置问题分开判断。在终端中执行：

curl -X POST "http://localhost:45650/hooks/agent" \
  -H "Authorization: Bearer YOUR_HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "请回复：Webhook配置成功",
    "agentId": "main",
    "name": "Webhook Test"
  }'

将命令中的YOUR_HOOK_TOKEN替换为openclaw.json里实际配置的hooks.token。localhost:45650表示请求发送端和网关位于同一台设备，端口不是默认值时也要换成当前实际端口。

请求内容中的参数表示：

message   交给智能体处理的任务内容
agentId   希望用于处理任务的智能体ID
name      本次任务在会话或记录中显示的名称

命令执行后，打开对话页面，查找名为Webhook Test的任务，也可以结合运行日志确认请求是否被接收。接口返回成功只表示任务已经进入智能体运行流程，不代表任务已经执行完成；还要确认main智能体实际收到并处理了任务，才能判断本机Webhook配置已经生效。

allowedAgentIds限制Webhook最终可以使用的智能体。使用本文示例时保持main在列表中即可；需要指定其他智能体时，应先确认ID有效，再把它加入允许列表。填写未知或不允许的ID时，实际路由可能受到默认智能体和允许列表的共同影响，因此不要依赖自动回退来选择处理者。

如果没有生成任务，优先检查请求地址是否包含完整的/hooks/agent、Authorization请求头是否使用Bearer格式、Token是否完全一致，以及目标智能体是否在allowedAgentIds允许范围内。

接入外部系统

本机测试通过后，再把Webhook配置到实际的外部系统。外部调用方不能使用localhost访问PlugClaw，需要使用它能够访问到的受保护入口。本文不根据设备IP推导外部Webhook地址；实际地址取决于PlugClaw的网络部署方式，应使用仅在可信网络中可访问的入口，或通过受信任的反向代理和HTTPS提供访问。不要在不了解安全影响的情况下直接把网关端口开放到公网。

外部系统需要按照本文测试请求的方式携带认证Token，并把事件内容转换为message等PlugClaw能够接收的字段。对方支持事件重试时，还应结合其官方说明确认重复请求的处理方式，避免同一事件重复触发任务。

接入完成后，用一条无风险的测试事件进行验证，同时检查外部系统的发送记录、PlugClaw中的会话和运行日志。三处信息能够对应起来，才说明外部系统已经真正接入成功。

需要临时停止接收Webhook时，可以把enabled改为false并重启网关。怀疑Token已经泄露时，应立即生成新的Token、替换发送方和PlugClaw中的旧值，再重启网关使旧Token失效。