OpenClaw Webhooks插件为外部系统提供认证HTTP路由，直接绑定TaskFlow。配置路由时需指定sessionKey和secret，支持从环境变量、文件或命令读取密钥，每个路由拥有独立的会话权限。可用动作包括create_flow、run_task、cancel_flow等。如果密钥解析失败，路由会被跳过并记录警告。

OpenClaw Webhooks插件配置指南：路由、认证与安全

Webhooks插件添加了经过认证的HTTP路由，将外部自动化与OpenClaw TaskFlow绑定在一起。

当你希望一个受信任的系统（如Zapier、n8n、CI任务或内部服务）无需先编写自定义插件，就能创建和驱动受管理的TaskFlow时，可以使用此插件。

运行位置

Webhooks插件运行在Gateway进程内部。

如果你的Gateway运行在另一台机器上，请在该Gateway主机上安装并配置此插件，然后重启Gateway。

配置路由

在plugins.entries.webhooks.config下设置配置：

json5

{
  plugins: {
    entries: {
      webhooks: {
        enabled: true,
        config: {
          routes: {
            zapier: {
              path: "/plugins/webhooks/zapier",
              sessionKey: "agent:main:main",
              secret: {
                source: "env",
                provider: "default",
                id: "OPENCLAW_WEBHOOK_SECRET",
              },
              controllerId: "webhooks/zapier",
              description: "Zapier TaskFlow bridge",
            },
          },
        },
      },
    },
  },
}

路由字段说明：

enabled: 可选，默认为true
path: 可选，默认为/plugins/webhooks/<routeId>
sessionKey: 必填，拥有所绑定TaskFlow的会话
secret: 必填，共享密钥或SecretRef
controllerId: 可选，为创建的受管理流程指定控制器ID
description: 可选，操作员备注

支持的secret输入：

纯文本字符串
带有source: "env" | "file" | "exec"的SecretRef

如果某密钥路由无法在启动时解析其密钥，插件会跳过该路由并记录警告，而不是暴露一个有问题的端点。

安全模型

每个路由都被信任以其配置的sessionKey的TaskFlow权限来行动。

这意味着该路由可以检查和修改该会话拥有的TaskFlow，因此你应该：

每个路由使用强唯一的密钥
优先使用密钥引用而非内联明文密钥
将路由绑定到适合工作流的最窄会话
只暴露你需要的具体webhook路径

插件应用了：

共享密钥认证
请求体大小和超时保护
固定窗口限速
并发请求限制
通过api.runtime.tasks.managedFlows.bindSession(...)实现的归属TaskFlow访问控制

请求格式

发送POST请求，携带：

Content-Type: application/json
Authorization: Bearer <secret>或x-openclaw-webhook-secret: <secret>

示例：

bash

curl -X POST https://gateway.example.com/plugins/webhooks/zapier \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_SHARED_SECRET' \
  -d '{"action":"create_flow","goal":"Review inbound queue"}'

支持的操作

插件目前接受以下JSON action值：

create_flow
get_flow
list_flows
find_latest_flow
resolve_flow
get_task_summary
set_waiting
resume_flow
finish_flow
fail_flow
request_cancel
cancel_flow
run_task

`create_flow`

为路由绑定的会话创建一个受管理的TaskFlow。

示例：

json

{
  "action": "create_flow",
  "goal": "Review inbound queue",
  "status": "queued",
  "notifyPolicy": "done_only"
}

`run_task`

在现有的受管理TaskFlow内创建一个受管理的子任务。

允许的运行时是：

subagent
acp

示例：

json

{
  "action": "run_task",
  "flowId": "flow_123",
  "runtime": "acp",
  "childSessionKey": "agent:main:acp:worker",
  "task": "Inspect the next message batch"
}

响应格式

成功的请求返回：

json

{
  "ok": true,
  "routeId": "zapier",
  "result": {}
}

被拒绝的请求返回：

json

{
  "ok": false,
  "routeId": "zapier",
  "code": "not_found",
  "error": "TaskFlow not found.",
  "result": {}
}

插件会主动从webhook响应中清理所有者/会话元数据。

常见问题

Webhooks路由启动时被跳过怎么办？

检查路由的secret配置是否能正确解析。如果使用环境变量（source: "env"），确认id对应的环境变量已设置且可访问。如果密钥解析失败，插件会跳过该路由并记录警告，不会暴露有问题的端点。

如何从环境变量设置Webhooks共享密钥？

在路由配置中使用SecretRef，设置source: "env"、provider: "default"，并将id设为环境变量名（例如OPENCLAW_WEBHOOK_SECRET）。在Gateway启动前确保该环境变量已正确赋值。

Webhooks插件支持哪些操作？

支持13种操作：create_flow、get_flow、list_flows、find_latest_flow、resolve_flow、get_task_summary、set_waiting、resume_flow、finish_flow、fail_flow、request_cancel、cancel_flow、run_task。其中run_task需要指定运行时（subagent或acp）和子会话密钥。

OpenClaw Webhooks插件配置指南：路由、认证与安全 ​

运行位置 ​

配置路由 ​

安全模型 ​

请求格式 ​

支持的操作 ​

create_flow ​

run_task ​

响应格式 ​

相关文档 ​

常见问题 ​

Webhooks路由启动时被跳过怎么办？ ​

如何从环境变量设置Webhooks共享密钥？ ​

Webhooks插件支持哪些操作？ ​

OpenClaw Webhooks插件配置指南：路由、认证与安全

运行位置

配置路由

安全模型

请求格式

支持的操作

`create_flow`

`run_task`

响应格式

相关文档

常见问题

Webhooks路由启动时被跳过怎么办？

如何从环境变量设置Webhooks共享密钥？

Webhooks插件支持哪些操作？