Zalo (Bot API)

Статус: экспериментальный. Только личные сообщения; группы скоро появятся согласно документации Zalo.

Требуется плагин

Zalo поставляется как плагин и не входит в основную установку.

  • Установка через CLI: openclaw plugins install @openclaw/zalo
  • Или выберите Zalo во время онбординга и подтвердите подсказку установки
  • Подробности: Плагины

Быстрая настройка (для начинающих)

  1. Установите плагин Zalo:
    • Из исходной копии: openclaw plugins install ./extensions/zalo
    • Из npm (если опубликовано): openclaw plugins install @openclaw/zalo
    • Или выберите Zalo при онбординге и подтвердите подсказку установки
  2. Установите токен:
    • Окружение: ZALO_BOT_TOKEN=...
    • Или конфигурация: channels.zalo.botToken: "...".
  3. Перезапустите шлюз (или завершите онбординг).
  4. Доступ к личным сообщениям по умолчанию использует сопряжение; утвердите код сопряжения при первом контакте.

Минимальная конфигурация:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing"
    }
  }
}

Что это такое

Zalo — это мессенджер, ориентированный на Вьетнам; его Bot API позволяет Gateway запускать бота для 1:1 разговоров. Это хорошо подходит для поддержки или уведомлений, где вы хотите детерминированную маршрутизацию обратно в Zalo.

  • Канал Zalo Bot API, принадлежащий Gateway.
  • Детерминированная маршрутизация: ответы возвращаются в Zalo; модель никогда не выбирает каналы.
  • Личные сообщения используют основную сессию агента.
  • Группы пока не поддерживаются (документация Zalo указывает "скоро").

Настройка (быстрый путь)

1) Создайте токен бота (Zalo Bot Platform)

  1. Перейдите на https://bot.zaloplatforms.com и войдите.
  2. Создайте нового бота и настройте его параметры.
  3. Скопируйте токен бота (формат: 12345689:abc-xyz).

2) Настройте токен (окружение или конфигурация)

Пример:

{
  channels: {
    zalo: {
      enabled: true,
      botToken: "12345689:abc-xyz",
      dmPolicy: "pairing"
    }
  }
}

Опция окружения: ZALO_BOT_TOKEN=... (работает только для учетной записи по умолчанию).

Поддержка нескольких учетных записей: используйте channels.zalo.accounts с токенами для каждой учетной записи и опциональным name.

  1. Перезапустите шлюз. Zalo запускается, когда токен разрешен (окружение или конфигурация).
  2. Доступ к личным сообщениям по умолчанию использует сопряжение. Утвердите код при первом контакте с ботом.

Как это работает (поведение)

  • Входящие сообщения нормализуются в общий конверт канала с заполнителями медиа.
  • Ответы всегда маршрутизируются обратно в тот же чат Zalo.
  • Длинный опрос по умолчанию; режим webhook доступен с channels.zalo.webhookUrl.

Ограничения

  • Исходящий текст разбивается на части по 2000 символов (лимит Zalo API).
  • Загрузки/выгрузки медиа ограничены channels.zalo.mediaMaxMb (по умолчанию 5).
  • Потоковая передача заблокирована по умолчанию из-за лимита в 2000 символов, делающего потоковую передачу менее полезной.

Контроль доступа (личные сообщения)

Доступ к личным сообщениям

  • По умолчанию: channels.zalo.dmPolicy = "pairing". Неизвестные отправители получают код сопряжения; сообщения игнорируются до утверждения (коды истекают через 1 час).
  • Утверждение через:
    • openclaw pairing list zalo
    • openclaw pairing approve zalo <CODE>
  • Сопряжение — это обмен токенами по умолчанию. Подробности: Сопряжение
  • channels.zalo.allowFrom принимает числовые ID пользователей (поиск по имени пользователя недоступен).

Длинный опрос против webhook

  • По умолчанию: длинный опрос (не требуется публичный URL).
  • Режим webhook: установите channels.zalo.webhookUrl и channels.zalo.webhookSecret.
    • Секрет webhook должен быть 8-256 символов.
    • URL webhook должен использовать HTTPS.
    • Zalo отправляет события с заголовком X-Bot-Api-Secret-Token для проверки.
    • Gateway HTTP обрабатывает запросы webhook на channels.zalo.webhookPath (по умолчанию путь webhook URL).

Примечание: getUpdates (опрос) и webhook взаимоисключающие согласно документации Zalo API.

Поддерживаемые типы сообщений

  • Текстовые сообщения: Полная поддержка с разбиением на части по 2000 символов.
  • Сообщения с изображениями: Загрузка и обработка входящих изображений; отправка изображений через sendPhoto.
  • Стикеры: Записываются в журнал, но не полностью обработаны (нет ответа агента).
  • Неподдерживаемые типы: Записываются в журнал (например, сообщения от защищенных пользователей).

Возможности

ФункцияСтатус
Личные сообщения✅ Поддерживается
Группы❌ Скоро (согласно документации Zalo)
Медиа (изображения)✅ Поддерживается
Реакции❌ Не поддерживается
Треды❌ Не поддерживается
Опросы❌ Не поддерживается
Нативные команды❌ Не поддерживается
Потоковая передача⚠️ Заблокирована (лимит 2000 символов)

Цели доставки (CLI/cron)

  • Используйте ID чата в качестве цели.
  • Пример: openclaw message send --channel zalo --target 123456789 --message "привет".

Устранение неполадок

Бот не отвечает:

  • Проверьте, что токен действителен: openclaw channels status --probe
  • Проверьте, что отправитель утвержден (сопряжение или allowFrom)
  • Проверьте журналы шлюза: openclaw logs --follow

Webhook не получает события:

  • Убедитесь, что URL webhook использует HTTPS
  • Проверьте, что секретный токен содержит 8-256 символов
  • Подтвердите, что конечная точка Gateway HTTP доступна по настроенному пути
  • Проверьте, что опрос getUpdates не работает (они взаимоисключающие)

Справочник по конфигурации (Zalo)

Полная конфигурация: Конфигурация

Опции провайдера:

  • channels.zalo.enabled: включить/отключить запуск канала.
  • channels.zalo.botToken: токен бота от Zalo Bot Platform.
  • channels.zalo.tokenFile: читать токен из файла.
  • channels.zalo.dmPolicy: pairing | allowlist | open | disabled (по умолчанию: pairing).
  • channels.zalo.allowFrom: список разрешений личных сообщений (ID пользователей). open требует "*". Мастер запросит числовые ID.
  • channels.zalo.mediaMaxMb: лимит входящих/исходящих медиа (МБ, по умолчанию 5).
  • channels.zalo.webhookUrl: включить режим webhook (требуется HTTPS).
  • channels.zalo.webhookSecret: секрет webhook (8-256 символов).
  • channels.zalo.webhookPath: путь webhook на HTTP-сервере шлюза.
  • channels.zalo.proxy: URL прокси для API-запросов.

Опции нескольких учетных записей:

  • channels.zalo.accounts.<id>.botToken: токен для каждой учетной записи.
  • channels.zalo.accounts.<id>.tokenFile: файл токена для каждой учетной записи.
  • channels.zalo.accounts.<id>.name: отображаемое имя.
  • channels.zalo.accounts.<id>.enabled: включить/отключить учетную запись.
  • channels.zalo.accounts.<id>.dmPolicy: политика личных сообщений для каждой учетной записи.
  • channels.zalo.accounts.<id>.allowFrom: список разрешений для каждой учетной записи.
  • channels.zalo.accounts.<id>.webhookUrl: URL webhook для каждой учетной записи.
  • channels.zalo.accounts.<id>.webhookSecret: секрет webhook для каждой учетной записи.
  • channels.zalo.accounts.<id>.webhookPath: путь webhook для каждой учетной записи.
  • channels.zalo.accounts.<id>.proxy: URL прокси для каждой учетной записи.
← Назад к документации