Webhooks 插件

概述

Webhooks 插件为 OpenClaw Gateway 添加经过认证的 HTTP 路由，将外部自动化系统（Zapier、n8n、CI 任务、内部服务等）绑定到 OpenClaw TaskFlow。无需编写自定义插件即可从外部系统创建和驱动托管 TaskFlow。插件运行在 Gateway 进程内部。

核心功能

• 认证路由：每个路由配置独立的共享密钥（支持明文字符串或 SecretRef），绑定到特定 sessionKey
• 安全模型：共享密钥认证 + 请求体大小/超时保护 + 固定窗口速率限制 + 并发请求限制 + 所有者绑定 TaskFlow 访问
• 支持的操作：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
• 请求格式：POST + Content-Type: application/json + Authorization: Bearer <secret> 或 x-openclaw-webhook-secret: <secret>
• 响应格式：{ "ok": true/false, "routeId": "...", "result": {} }，响应中不包含 owner/session 元数据

配置/使用

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

安全建议：

• 每个路由使用强唯一密钥
• 优先使用 SecretRef 而非内联明文密钥
• 将路由绑定到最窄的 session

run_task 支持的运行时：subagent、acp

相关页面

• concepts/plugin-sdk-runtime — Plugin SDK 运行时辅助工具
• concepts/tool-lobster — Lobster 工作流引擎（TaskFlow 相关）
• concepts/tool-acp-agents — ACP Agents 外部 harness 运行时