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 桥接器",
            },
          },
        },
      },
    },
  },
}

路由字段：

字段	必需	默认	说明
`enabled`	否	`true`
`path`	否	`/plugins/webhooks/<routeId>`	必须在所有路由中保持唯一。
`sessionKey`	是	-	拥有绑定 TaskFlows 的会话。
`secret`	是	-	纯字符串或 SecretRef（见下文）。
`controllerId`	否	`webhooks/<routeId>`	用作默认的 `create_flow` 控制器。
`description`	否	-	仅供操作人员备注。

secret 接受纯字符串或 SecretRef：{ source: "env" | "file" | "exec" | "store", provider: "default", id: "..." }。 SecretRefs 会解析到 Gateway 的启动配置快照中。当某个路由的 secret 无法解析时，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`	通过不透明 token 解析 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": "审查传入队列",
  "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": "检查下一批消息"
}

响应格式

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

{
  "ok": false,
  "routeId": "zapier",
  "code": "not_found",
  "error": "未找到 TaskFlow。",
  "result": {}
}

Flow 和 task 视图绝不会包含 owner/session 元数据，因此响应不能泄露路由绑定的 sessionKey。code 值包括 not_found、 not_managed、revision_conflict、persist_failed、cancel_requested、 cancel_pending、terminal、invalid_request、request_rejected，以及当某个 mutation 因上面列出的代码未涵盖的原因被拒绝时使用的特定于 action 的回退代码（mutation_rejected、create_rejected、 task_not_created、cancel_rejected）。

概览

插件

插件指南

构建插件

技能

自动化

工具

智能体协作

配置路由

安全模型

请求格式

支持的动作

`create_flow`

`run_task`

响应格式

相关

​配置路由

​安全模型

​请求格式

​支持的动作

​create_flow

​run_task

​响应格式

​相关

配置路由

安全模型

请求格式

支持的动作

`create_flow`

`run_task`

响应格式

相关