Zalo (Bot API)

Статус: экспериментальный. ЛС поддерживаются; обработка групп доступна с явным контролем групповой политики.

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

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

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

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

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

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

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

Что это

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

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

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

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

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

2) Настройка токена (env или конфиг)

Пример:

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

Вариант с env: ZALO_BOT_TOKEN=... (работает только для аккаунта по умолчанию).

Мульти-аккаунт: используйте channels.zalo.accounts с токенами и необязательным name для каждого аккаунта.

  1. Перезапустите шлюз. Zalo запускается, когда токен доступен (env или конфиг).
  2. Доступ к ЛС по умолчанию использует спаривание. Подтвердите код при первом контакте.

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

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

Ограничения

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

Контроль доступа (ЛС)

Доступ к ЛС

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

Контроль доступа (группы)

  • channels.zalo.groupPolicy управляет обработкой входящих групповых сообщений: open | allowlist | disabled.
  • Поведение по умолчанию закрыто: allowlist.
  • channels.zalo.groupAllowFrom ограничивает, какие ID отправителей могут активировать бота в группах.
  • Если groupAllowFrom не задан, Zalo использует fallback к allowFrom для проверки отправителей.
  • groupPolicy: "disabled" блокирует все групповые сообщения.
  • groupPolicy: "open" разрешает любого участника группы (с требованием упоминания).
  • Примечание: если channels.zalo полностью отсутствует, runtime всё равно использует fallback к groupPolicy="allowlist" для безопасности.

Long-polling vs вебхук

  • По умолчанию: long-polling (публичный URL не требуется).
  • Режим вебхука: задайте channels.zalo.webhookUrl и channels.zalo.webhookSecret.
    • Секрет вебхука должен содержать 8-256 символов.
    • URL вебхука должен использовать HTTPS.
    • Zalo отправляет события с заголовком X-Bot-Api-Secret-Token для верификации.
    • HTTP шлюза обрабатывает запросы вебхука по пути channels.zalo.webhookPath (по умолчанию — путь из URL вебхука).
    • Запросы должны использовать Content-Type: application/json (или +json медиа-типы).
    • Дублирующие события (event_name + message_id) игнорируются в течение короткого окна повтора.
    • Пиковый трафик ограничен по частоте на путь/источник и может вернуть HTTP 429.

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

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

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

Возможности

ФункцияСтатус
Прямые сообщенияПоддерживается
ГруппыПоддерживается с контролем политики (allowlist по умолчанию)
Медиа (изображения)Поддерживается
РеакцииНе поддерживается
Потоки (threads)Не поддерживается
ОпросыНе поддерживается
Нативные командыНе поддерживается
СтримингЗаблокирован (лимит 2000 символов)

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

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

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

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

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

Вебхук не получает события:

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

Справочник конфигурации (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.groupPolicy: open | allowlist | disabled (по умолчанию: allowlist).
  • channels.zalo.groupAllowFrom: список доступа для отправителей в группах (ID пользователей). При отсутствии используется fallback к allowFrom.
  • channels.zalo.mediaMaxMb: лимит медиа (МБ, по умолчанию 5).
  • channels.zalo.webhookUrl: включение режима вебхука (требуется HTTPS).
  • channels.zalo.webhookSecret: секрет вебхука (8-256 символов).
  • channels.zalo.webhookPath: путь вебхука на 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>.groupPolicy: групповая политика аккаунта.
  • channels.zalo.accounts.<id>.groupAllowFrom: список доступа для отправителей в группах аккаунта.
  • channels.zalo.accounts.<id>.webhookUrl: URL вебхука аккаунта.
  • channels.zalo.accounts.<id>.webhookSecret: секрет вебхука аккаунта.
  • channels.zalo.accounts.<id>.webhookPath: путь вебхука аккаунта.
  • channels.zalo.accounts.<id>.proxy: URL прокси аккаунта.
arrow_back
Назад
Whatsapp
Далее
Zalouser
arrow_forward