Перейти к основному содержанию
Плагин Webhooks добавляет аутентифицированные HTTP-маршруты, которые связывают внешнюю автоматизацию с OpenClaw TaskFlow. Используйте его, когда нужно, чтобы доверенная система, например Zapier, n8n, задание CI или внутренний сервис, создавала управляемые TaskFlow и управляла ими без предварительного написания пользовательского плагина.

​
Где он запускается

Плагин Webhooks запускается внутри процесса Gateway. Если ваш 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: необязательный идентификатор контроллера для создаваемых управляемых потоков
  • description: необязательная заметка для оператора
Поддерживаемые входные значения secret:
  • Обычная строка
  • SecretRef с source: "env" | "file" | "exec"
Если маршрут, использующий секрет, не может разрешить свой секрет при запуске, плагин пропускает этот маршрут и записывает предупреждение вместо того, чтобы открывать неработающую конечную точку.

​
Модель безопасности

Каждому маршруту доверено действовать с полномочиями TaskFlow, заданными его настроенным sessionKey. Это означает, что маршрут может проверять и изменять TaskFlow, принадлежащие этой сессии, поэтому следует:
  • Использовать надежный уникальный секрет для каждого маршрута
  • Предпочитать ссылки на секреты встроенным секретам в открытом тексте
  • Привязывать маршруты к самой узкой сессии, подходящей для рабочего процесса
  • Открывать только конкретный путь Webhook, который вам нужен
Плагин применяет:
  • Аутентификацию по общему секрету
  • Ограничения размера тела запроса и тайм-аутов
  • Ограничение частоты по фиксированному окну
  • Ограничение параллельных запросов
  • Доступ к TaskFlow в границах владельца через api.runtime.tasks.managedFlows.bindSession(...)

​
Формат запроса

Отправляйте запросы 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"}'

​
Поддерживаемые действия

Сейчас плагин принимает следующие 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

Создает управляемый TaskFlow для привязанной к маршруту сессии. Пример: 
{
  "action": "create_flow",
  "goal": "Review inbound queue",
  "status": "queued",
  "notifyPolicy": "done_only"
}

​
run_task

Создает управляемую дочернюю задачу внутри существующего управляемого TaskFlow. Разрешенные среды выполнения:
  • 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": {}
}
Плагин намеренно удаляет метаданные владельца и сессии из ответов Webhook.

​
Связанная документация