Webhooks 插件

Webhooks 插件会添加经过身份验证的 HTTP 路由，使受信任的外部系统（Zapier、n8n、CI 作业、内部服务）无需编写自定义插件，即可通过 HTTP 创建和驱动托管的 OpenClaw TaskFlow。该插件在 Gateway 网关进程内运行。对于远程 Gateway 网关，请在相应主机上安装并配置该插件，然后重启 Gateway 网关。该插件默认未配置任何路由，因此在添加至少一个路由前不会执行任何操作。

配置路由

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

{
  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`	否	`webhooks/<routeId>`	用作默认的 `create_flow` 控制器。
`description`	否	-	仅供操作员备注。

secret 接受纯文本字符串或 SecretRef：{ source: "env" | "file" | "exec", provider: "default", id: "..." }。 SecretRef 会解析到 Gateway 网关的启动配置快照中。当某个路由的密钥无法解析时，Gateway 网关会继续运行，该路由也会保持注册但处于冷状态：请求会收到通用的身份验证失败响应（401）。其他路由仍然可用。修复 SecretRef 来源后，重新加载或重启 Gateway 网关以激活新快照。绝不会在公共请求路径上解析 SecretRef 值。

安全模型

每个路由都拥有其所配置 sessionKey 的 TaskFlow 权限：它可以检查和修改该会话拥有的任何 TaskFlow。TaskFlow 访问始终通过 api.runtime.tasks.managedFlows.bindSession(...) 进行，因此路由绝不能在其绑定会话之外执行操作。为限制影响范围：

为每个路由使用强度高且唯一的密钥。
优先使用 SecretRef，而不是内联的明文密钥。
将路由绑定到能够满足工作流需求的最小范围会话。
仅公开所需的特定 webhook 路径。

每个路径的请求处理顺序为：HTTP 方法（仅限 POST）和 Content-Type: application/json 检查，然后进行固定窗口速率限制（每个路径+客户端 IP 键在每个 60 秒窗口内最多 120 个请求，最多跟踪 4,096 个键），接着进行进行中请求限制（每个键最多 8 个并发请求，最多跟踪 4,096 个键），然后进行共享密钥身份验证，最后读取大小上限为 256 KB、超时为 15 秒的 JSON 正文。未通过前置检查的请求不会进入后续阶段。

请求格式

发送 POST 请求，使用 Content-Type: application/json，并提供 Authorization: Bearer <secret> 或 x-openclaw-webhook-secret: <secret>：

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"}'

支持的操作

操作	用途
`create_flow`	为路由的会话创建托管 TaskFlow。
`get_flow`	按 ID 获取一个 TaskFlow。
`list_flows`	列出路由会话的 TaskFlow。
`find_latest_flow`	获取最近更新的 TaskFlow。
`resolve_flow`	通过不透明令牌解析 TaskFlow。
`get_task_summary`	获取 TaskFlow 的任务摘要。
`set_waiting`	将 TaskFlow 标记为等待中，可选择提供状态/等待数据。
`resume_flow`	恢复等待中/已阻塞的 TaskFlow。
`finish_flow`	将 TaskFlow 标记为已完成。
`fail_flow`	将 TaskFlow 标记为失败。
`request_cancel`	请求协作式取消。
`cancel_flow`	取消 TaskFlow（如果子任务仍处于活动状态，可能返回 `202`）。
`run_task`	在现有 TaskFlow 中创建托管子任务。

修改操作（set_waiting、resume_flow、finish_flow、fail_flow、request_cancel）需要提供 flowId 和 expectedRevision 以实现乐观并发控制；过期的修订版本会返回 409 revision_conflict。

`create_flow`

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

`run_task`

允许的 runtime 值：subagent、acp。startedAt、lastEventAt 和 progressSummary 仅在 status 为 "running" 时有效；在任何其他状态下发送这些值都会返回 400 invalid_request。

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

响应结构

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

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

流程和任务视图绝不包含所有者/会话元数据，因此响应不会泄露路由绑定的 sessionKey。code 值包括 not_found、not_managed、revision_conflict、persist_failed、cancel_requested、cancel_pending、terminal、invalid_request、request_rejected，以及操作特定的回退代码（mutation_rejected、create_rejected、task_not_created、cancel_rejected）；当修改因上述命名代码未涵盖的原因而被拒绝时，会使用这些回退代码。

概览

Plugins

扩展

Building plugins

技能

自动化与任务

内置工具

代理协作

配置路由

安全模型

请求格式

支持的操作

`create_flow`

`run_task`

响应结构

相关内容

​配置路由

​安全模型

​请求格式

​支持的操作

​create_flow

​run_task

​响应结构

​相关内容

配置路由

安全模型

请求格式

支持的操作

`create_flow`

`run_task`

响应结构

相关内容