---
read_when:
    - 你希望从外部系统触发或驱动 TaskFlow
    - 你正在配置内置的 Webhooks 插件
summary: Webhooks 插件：面向受信任外部自动化的经过身份验证的 TaskFlow 入口
title: Webhooks 插件
x-i18n:
    generated_at: "2026-07-26T06:55:10Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 77e455450d6183635c76a1e8002feeb287deb4ff242dbd555ef9d0f2b21ce5f6
    source_path: plugins/webhooks.md
    workflow: 16
---

Webhooks 插件会添加经过身份验证的 HTTP 路由，使受信任的外部系统（Zapier、n8n、CI 作业、内部服务）无需编写自定义插件，即可通过 HTTP 创建和驱动托管的 OpenClaw TaskFlow。

该插件在 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` | 否       | `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>`：

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

## 支持的操作

| 操作               | 用途                                                               |
| ------------------ | ------------------------------------------------------------------ |
| `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`

```json
{
  "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`。

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

流程和任务视图绝不包含所有者/会话元数据，因此响应不会泄露路由绑定的 `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`）；当修改因上述命名代码未涵盖的原因而被拒绝时，会使用这些回退代码。

## 相关内容

- [Hooks](/zh-CN/automation/hooks) - 内部事件驱动的钩子与此基于 HTTP 的 TaskFlow 桥接器对比
- [Gateway 网关 Webhooks（`hooks.*` 配置）](/zh-CN/automation/cron-jobs#webhooks) - 独立的通用 Gateway 网关 HTTP 端点功能；与此插件的路由不同
- [插件运行时 SDK](/zh-CN/plugins/sdk-runtime)
- [CLI Webhooks](/zh-CN/cli/webhooks)