Zalo

Статус: экспериментальный. Реализованы как личные сообщения, так и групповые чаты; приведённая ниже таблица Возможности отражает поведение, проверенное для ботов Zalo Bot Creator / Marketplace.

Встроенный плагин

В текущих выпусках OpenClaw Zalo поставляется как встроенный плагин, поэтому для пакетных сборок отдельная установка не требуется.

Для более старой сборки или пользовательской установки без Zalo установите пакет npm напрямую:

• Установка: openclaw plugins install @openclaw/zalo
• Зафиксированная версия: openclaw plugins install @openclaw/zalo@2026.6.11
• Из локальной рабочей копии: openclaw plugins install ./path/to/local/zalo-plugin
• Подробнее: Плагины

Быстрая настройка

1. Создайте токен бота на https://bot.zaloplatforms.com (войдите в систему, создайте бота и настройте параметры). Токен — numeric_id:secret; для ботов Marketplace пригодный для выполнения токен может содержаться в приветственном сообщении бота.
2. Укажите токен либо в переменной окружения ZALO_BOT_TOKEN=... (только для учётной записи по умолчанию), либо в конфигурации.
3. Перезапустите Gateway.
4. При первом обращении в личных сообщениях подтвердите код сопряжения (политика личных сообщений по умолчанию — сопряжение).

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

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

Несколько учётных записей: добавьте дополнительные записи в channels.zalo.accounts.<id>, указав для каждой собственные botToken/name. channels.zalo.botToken (плоская форма без accounts) — устаревшая сокращённая запись для одной учётной записи; для новых конфигураций предпочитайте accounts.<id>.*.

Что это такое

Zalo — ориентированное на Вьетнам приложение для обмена сообщениями. Его Bot API позволяет Gateway запускать бота как для личных бесед, так и для групповых чатов с детерминированной маршрутизацией ответов обратно в Zalo (модель никогда не выбирает каналы).

Эта страница посвящена ботам Zalo Bot Creator / Marketplace. Боты Zalo Official Account (OA) относятся к другой части продукта и могут вести себя иначе; на этой странице они не рассматриваются.

Принцип работы

• Входящие сообщения нормализуются в общий конверт канала с заполнителями для медиафайлов.
• Ответы всегда направляются обратно в тот же чат Zalo; ответы с цитированием не используются (replyToMode всегда отключён).
• По умолчанию используется длительный опрос (getUpdates); режим Webhook доступен через channels.zalo.webhookUrl.
• В группах для активации бота требуется @упоминание; это нельзя настроить отдельно для канала.

Ограничения

Управление доступом

Личные сообщения

• channels.zalo.dmPolicy: pairing (по умолчанию) | allowlist | open | disabled.
• Сопряжение: неизвестные отправители получают код сопряжения; сообщения игнорируются до его подтверждения. Срок действия кодов истекает через 1 час.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Подробнее: Сопряжение
• channels.zalo.allowFrom принимает числовые идентификаторы пользователей Zalo (поиск по имени пользователя не поддерживается). Для open требуется "*".

Группы

Групповые чаты поддерживаются плагином (chatTypes: ["direct", "group"]) и ограничиваются требованием упоминания и групповой политикой:

• channels.zalo.groupPolicy: open | allowlist | disabled.
• channels.zalo.groupAllowFrom ограничивает идентификаторы отправителей, которые могут активировать бота в группах; если значение не задано, используется allowFrom.
• Разрешение по умолчанию: если настроен channels.zalo, незаданный groupPolicy принимает значение open. Если channels.zalo полностью отсутствует, среда выполнения безопасно отклоняет доступ, устанавливая allowlist.
• Известное ограничение на практике: в некоторых конфигурациях ботов Marketplace бота вообще невозможно добавить в группу. Если вы столкнулись с этим, проверьте настройки своего бота на Zalo Bot Platform; это ограничение платформы, а не политика OpenClaw.

Длительный опрос и Webhook

• По умолчанию: длительный опрос (публичный URL не требуется).
• Режим Webhook: задайте channels.zalo.webhookUrl и channels.zalo.webhookSecret.
  • URL Webhook должен использовать HTTPS.
  • Секрет Webhook должен содержать 8–256 символов.
  • Zalo отправляет события с заголовком X-Bot-Api-Secret-Token, который проверяется сравнением с постоянным временем выполнения.
  • HTTP-сервер Gateway обрабатывает запросы Webhook по пути channels.zalo.webhookPath (по умолчанию используется путь из URL Webhook).
  • Запросы должны использовать Content-Type: application/json (или тип медиа +json).
  • Согласно документации API Zalo, опрос getUpdates и Webhook являются взаимоисключающими.

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

• Текст: полная поддержка, с разделением на фрагменты по 2000 символов.
• Медиафайлы: входящие и исходящие, с ограничением mediaMaxMb.
• Реакции, ветки, опросы и нативные команды: плагином не поддерживаются.
• Потоковая передача: плагин заявляет поддержку потоковой передачи блоков, но Zalo не предоставляет отдельных параметров настройки очереди исходящих сообщений или объединения текста (в отличие от некоторых других региональных каналов); если это важно для вашего сценария, проверьте текущее поведение в своей среде.

Возможности

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

Используйте идентификатор чата в качестве цели:

openclaw message send --channel zalo --target 123456789 --message "hi"

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

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

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

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

• Убедитесь, что URL Webhook использует HTTPS
• Убедитесь, что секрет содержит 8–256 символов
• Убедитесь, что HTTP-конечная точка Gateway доступна по настроенному пути
• Убедитесь, что опрос getUpdates не выполняется одновременно (они взаимоисключающие)
• Всплеск запросов может привести к ответу HTTP 429 (120 запросов / 60 с на комбинацию пути и IP-адреса); увеличьте интервал и повторите попытку

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

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

channels.zalo.botToken, channels.zalo.dmPolicy и другие плоские ключи верхнего уровня являются устаревшей сокращённой записью для одной учётной записи, соответствующей указанным выше полям; поддерживаются обе формы.

Параметр окружения: ZALO_BOT_TOKEN=... задаёт токен только для учётной записи по умолчанию.

Связанные материалы

• Обзор каналов — все поддерживаемые каналы
• Сопряжение — аутентификация в личных сообщениях и процесс сопряжения
• Группы — поведение групповых чатов и активация по упоминанию
• Маршрутизация каналов — маршрутизация сеансов для сообщений
• Безопасность — модель доступа и усиление защиты