Webhooks Plugin - OpenClaw

Webhooks Plugin 會新增已驗證的 HTTP 路由，將外部自動化綁定到 OpenClaw TaskFlow。當你想讓 Zapier、n8n、CI 作業或內部服務等受信任系統建立並驅動受管理的 TaskFlow，而不想先撰寫自訂 Plugin 時，請使用它。

執行位置

Webhooks Plugin 會在 Gateway 程序內執行。如果你的 Gateway 在另一台機器上執行，請在該 Gateway 主機上安裝並設定 Plugin，然後重新啟動 Gateway。

設定路由

在 plugins.entries.webhooks.config 下設定 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 的 session
secret：必要，共用密鑰或 SecretRef
controllerId：選用，供已建立受管理流程使用的 controller id
description：選用，操作員註記

支援的 secret 輸入：

純文字字串
SecretRef，搭配 source: "env" | "file" | "exec"

如果由密鑰支援的路由在啟動時無法解析其密鑰，Plugin 會略過該路由並記錄警告，而不是暴露損壞的 endpoint。

安全模型

每個路由都會被信任，可使用其設定的 sessionKey 的 TaskFlow 權限執行操作。這表示該路由可以檢查並變更該 session 擁有的 TaskFlow，因此你應該：

為每個路由使用強式且唯一的密鑰
優先使用密鑰參照，而不是內嵌純文字密鑰
將路由綁定到符合工作流程的最小範圍 session
只暴露你需要的特定 Webhook 路徑

Plugin 會套用：

共用密鑰驗證
請求 body 大小與逾時防護
固定視窗速率限制
進行中請求限制
透過 api.runtime.tasks.managedFlows.bindSession(...) 進行的 owner 綁定 TaskFlow 存取

請求格式

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

支援的動作

Plugin 目前接受下列 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`

為路由綁定的 session 建立受管理的 TaskFlow。範例：

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

`run_task`

在既有受管理 TaskFlow 內建立受管理的子任務。允許的 runtime 為：

subagent
acp

範例：

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

Plugin 會刻意從 Webhook 回應中清除 owner/session metadata。

Documentation Index

​執行位置

​設定路由

​安全模型

​請求格式

​支援的動作

​create_flow

​run_task

​回應形狀

​相關文件