Вебхуки¶

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): Описание события (например, «Получено новое письмо»).
• mode необязательно (now | next-heartbeat): Нужно ли запускать немедленный сигнал keepalive (по умолчанию now) или ждать следующей периодической проверки.

Эффект:

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

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): Нужно ли запускать немедленный сигнал keepalive (по умолчанию now) или ждать следующей периодической проверки.
• deliver необязательно (boolean): Если true, ответ агента будет отправлен в канал сообщений. По умолчанию — true. Ответы, которые являются лишь подтверждениями keepalive, автоматически пропускаются.
• 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, запускает немедленный сигнал keepalive

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 см. в Gmail Pub/Sub.

Ответы¶

• 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 в маппинге этого хука (опасно).