Веб-хуки

Gateway может открыть небольшую HTTP-конечную точку веб-хука для внешних триггеров.

Включение

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks"
  }
}

Примечания:

  • hooks.token обязателен, когда hooks.enabled=true.
  • hooks.path по умолчанию /hooks.

Аутентификация

Каждый запрос должен включать токен хука. Предпочитайте заголовки:

  • Authorization: Bearer <token> (рекомендуется)
  • x-openclaw-token: <token>
  • ?token=<token> (устарело; записывает предупреждение и будет удалено в будущей мажорной версии)

Конечные точки

POST /hooks/wake

Полезная нагрузка:

{ "text": "System line", "mode": "now" }
  • text обязательно (string): Описание события (например, "New email received").
  • mode опционально (now | next-heartbeat): Запускать ли немедленное сердцебиение (по умолчанию now) или ждать следующей периодической проверки.

Эффект:

  • Ставит в очередь системное событие для основной сессии
  • Если mode=now, запускает немедленное сердцебиение

POST /hooks/agent

Полезная нагрузка:

{
  "message": "Run this",
  "name": "Email",
  "sessionKey": "hook:email:msg-123",
  "wakeMode": "now",
  "deliver": true,
  "channel": "last",
  "to": "+15551234567",
  "model": "openai/gpt-5.2-mini",
  "thinking": "low",
  "timeoutSeconds": 120
}
  • message обязательно (string): Промпт или сообщение для обработки агентом.
  • name опционально (string): Человекочитаемое имя хука (например, "GitHub"), используется как префикс в сводках сессии.
  • sessionKey опционально (string): Ключ, используемый для идентификации сессии агента. По умолчанию случайный hook:<uuid>. Использование постоянного ключа позволяет вести многооборотную беседу в контексте хука.
  • wakeMode опционально (now | next-heartbeat): Запускать ли немедленное сердцебиение (по умолчанию now) или ждать следующей периодической проверки.
  • deliver опционально (boolean): Если true, ответ агента будет отправлен в канал обмена сообщениями. По умолчанию true. Ответы, которые являются только подтверждениями сердцебиения, автоматически пропускаются.
  • channel опционально (string): Канал обмена сообщениями для доставки. Один из: last, whatsapp, telegram, discord, slack, mattermost (плагин), signal, imessage, msteams. По умолчанию last.
  • to опционально (string): Идентификатор получателя для канала (например, номер телефона для WhatsApp/Signal, ID чата для Telegram, ID канала для Discord/Slack/Mattermost (плагин), ID беседы для MS Teams). По умолчанию последний получатель в основной сессии.
  • model опционально (string): Переопределение модели (например, anthropic/claude-3-5-sonnet или алиас). Должна быть в списке разрешенных моделей, если ограничено.
  • thinking опционально (string): Переопределение уровня мышления (например, low, medium, high).
  • timeoutSeconds опционально (number): Максимальная продолжительность запуска агента в секундах.

Эффект:

  • Выполняет изолированный ход агента (собственный ключ сессии)
  • Всегда публикует сводку в основной сессии
  • Если wakeMode=now, запускает немедленное сердцебиение

POST /hooks/<name> (отображено)

Пользовательские имена хуков разрешаются через hooks.mappings (см. конфигурацию). Отображение может превратить произвольные полезные нагрузки в действия wake или agent, с опциональными шаблонами или преобразованиями кода.

Варианты отображения (кратко):

  • hooks.presets: ["gmail"] включает встроенное отображение Gmail.
  • hooks.mappings позволяет определить match, action и шаблоны в конфигурации.
  • hooks.transformsDir + transform.module загружает модуль JS/TS для пользовательской логики.
  • Используйте match.source для сохранения общей конечной точки приема (маршрутизация на основе полезной нагрузки).
  • Преобразования TS требуют загрузчика TS (например, bun или tsx) или предварительно скомпилированного .js во время выполнения.
  • Установите deliver: true + channel/to в отображениях для направления ответов на поверхность чата (channel по умолчанию last и возвращается к WhatsApp).
  • allowUnsafeExternalContent: true отключает обертку безопасности внешнего содержимого для этого хука (опасно; только для доверенных внутренних источников).
  • openclaw webhooks gmail setup записывает конфигурацию hooks.gmail для openclaw webhooks gmail run. См. Gmail Pub/Sub для полного потока Gmail watch.

Ответы

  • 200 для /hooks/wake
  • 202 для /hooks/agent (асинхронный запуск начат)
  • 401 при сбое аутентификации
  • 400 при недопустимой полезной нагрузке
  • 413 при слишком больших полезных нагрузках

Примеры

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"text":"New email received","mode":"now"}'

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","wakeMode":"next-heartbeat"}'

Использование другой модели

Добавьте model в полезную нагрузку агента (или отображение), чтобы переопределить модель для этого запуска:

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H 'x-openclaw-token: SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.2-mini"}'

Если вы применяете agents.defaults.models, убедитесь, что переопределяющая модель включена туда.

curl -X POST http://127.0.0.1:18789/hooks/gmail \
  -H 'Authorization: Bearer SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"source":"gmail","messages":[{"from":"Ada","subject":"Hello","snippet":"Hi"}]}'

Безопасность

  • Держите конечные точки хуков за loopback, tailnet или доверенным обратным прокси.
  • Используйте выделенный токен хука; не переиспользуйте токены аутентификации gateway.
  • Избегайте включения конфиденциальных сырых полезных нагрузок в логи веб-хуков.
  • Полезные нагрузки хуков рассматриваются как недоверенные и по умолчанию обернуты границами безопасности. Если вам необходимо отключить это для конкретного хука, установите allowUnsafeExternalContent: true в отображении этого хука (опасно).
← Назад к документации