Автоматизация

Вебхуки

Шлюз может предоставлять небольшой HTTP-эндпоинт для вебхуков для внешних триггеров.

Включение

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    // Опционально: ограничить явную маршрутизацию по `agentId` этим списком разрешений.
    // Пропустите или включите "*", чтобы разрешить любого агента.
    // Установите [], чтобы запретить всю явную маршрутизацию по `agentId`.
    allowedAgentIds: ["hooks", "main"],
  },
}

Примечания:

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

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

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

  • Authorization: Bearer <token> (рекомендуется)
  • x-openclaw-token: <token>
  • Токены в строке запроса отклоняются (?token=... возвращает 400).

Эндпоинты

POST /hooks/wake

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

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

Эффект:

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

POST /hooks/agent

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

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

Эффект:

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

Политика ключа сессии (критическое изменение)

Переопределения sessionKey в полезной нагрузке /hooks/agent отключены по умолчанию.

  • Рекомендуется: установить фиксированный hooks.defaultSessionKey и запретить переопределения из запросов.
  • Опционально: разрешать переопределения из запросов только при необходимости и ограничивать префиксы.

Рекомендуемая конфигурация:

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
  },
}

Конфигурация для совместимости (устаревшее поведение):

{
  hooks: {
    enabled: true,
    token: "${OPENCLAW_HOOKS_TOKEN}",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:"], // настоятельно рекомендуется
  },
}

POST /hooks/<name> (сопоставленные)

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

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

Ответы

  • 200 для /hooks/wake
  • 200 для /hooks/agent (асинхронный запуск принят)
  • 401 при ошибке аутентификации
  • 429 после повторных ошибок аутентификации от одного клиента (проверьте Retry-After)
  • 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 или доверенным обратным прокси.
  • Используйте выделенный токен для вебхуков; не используйте повторно токены аутентификации шлюза.
  • Повторные ошибки аутентификации ограничиваются по частоте на клиентский адрес, чтобы замедлить попытки перебора.
  • Если вы используете маршрутизацию между несколькими агентами, установите hooks.allowedAgentIds, чтобы ограничить явный выбор agentId.
  • Держите hooks.allowRequestSessionKey=false, если вам не требуются сессии, выбираемые вызывающей стороной.
  • Если вы разрешаете sessionKey из запроса, ограничьте hooks.allowedSessionKeyPrefixes (например, ["hook:"]).
  • Избегайте включения чувствительных исходных полезных нагрузок в логи вебхуков.
  • Полезные нагрузки вебхуков по умолчанию считаются ненадежными и оборачиваются границами безопасности. Если вы должны отключить это для конкретного вебхука, установите allowUnsafeExternalContent: true в сопоставлении этого вебхука (опасно).

Устранение неполадок автоматизацииGmail PubSub