Zalo

​

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

• Установка: 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",
        },
      },
    },
  },
}

​

Что это такое

​

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

• Входящие сообщения нормализуются в общий конверт канала с заполнителями для медиафайлов.
• Ответы всегда направляются обратно в тот же чат 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 требуется "*".

​

Группы

• 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

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

​

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

​

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

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