Zalo - OpenClaw

Статус: экспериментально. Личные сообщения поддерживаются. Раздел Возможности ниже отражает текущее поведение Marketplace-ботов.

Встроенный plugin

Zalo поставляется как встроенный plugin в текущих выпусках OpenClaw, поэтому обычным пакетным сборкам не требуется отдельная установка. Если вы используете более старую сборку или пользовательскую установку, исключающую Zalo, установите npm-пакет напрямую:

Установка через CLI: openclaw plugins install @openclaw/zalo
Закрепленная версия: openclaw plugins install @openclaw/zalo@2026.5.2
Или из исходного checkout: openclaw plugins install ./path/to/local/zalo-plugin
Подробности: Plugins

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

Убедитесь, что plugin Zalo доступен.
- Текущие пакетные выпуски OpenClaw уже включают его.
- Более старые/пользовательские установки могут добавить его вручную с помощью команд выше.
Задайте токен:
- Env: ZALO_BOT_TOKEN=...
- Или config: channels.zalo.accounts.default.botToken: "...".
Перезапустите gateway (или завершите настройку).
Доступ к личным сообщениям по умолчанию выполняется через pairing; подтвердите код pairing при первом контакте.

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

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

Что это такое

Zalo — ориентированное на Вьетнам приложение для обмена сообщениями; его Bot API позволяет Gateway запускать бота для разговоров 1:1. Это хорошо подходит для поддержки или уведомлений, когда нужна детерминированная маршрутизация обратно в Zalo. Эта страница отражает текущее поведение OpenClaw для ботов Zalo Bot Creator / Marketplace. Боты Zalo Official Account (OA) относятся к другой поверхности продукта Zalo и могут вести себя иначе.

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

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

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

Перейдите на https://bot.zaloplatforms.com и войдите в систему.
Создайте нового бота и настройте его параметры.
Скопируйте полный токен бота (обычно numeric_id:secret). Для Marketplace-ботов пригодный для runtime токен может появиться в приветственном сообщении бота после создания.

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

Пример:

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

Если позже вы перейдете на поверхность бота Zalo, где доступны группы, можно явно добавить конфигурацию для групп, например groupPolicy и groupAllowFrom. О текущем поведении Marketplace-ботов см. Возможности. Вариант env: ZALO_BOT_TOKEN=... (работает только для учетной записи по умолчанию). Поддержка нескольких учетных записей: используйте channels.zalo.accounts с токенами для каждой учетной записи и необязательным name.

Перезапустите gateway. Zalo запускается, когда токен найден (env или config).
Для доступа к личным сообщениям по умолчанию используется pairing. Подтвердите код при первом обращении к боту.

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

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

Ограничения

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

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

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

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

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

Для ботов Zalo Bot Creator / Marketplace поддержка групп на практике была недоступна, потому что бота вообще нельзя было добавить в группу. Это означает, что приведенные ниже ключи конфигурации, связанные с группами, существуют в схеме, но не были пригодны для Marketplace-ботов:

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

Значения политики групп (когда доступ к группам доступен на поверхности вашего бота):

groupPolicy: "disabled" — блокирует все групповые сообщения.
groupPolicy: "open" — разрешает любого участника группы (с проверкой упоминания).
groupPolicy: "allowlist" — отказ по умолчанию; принимаются только разрешенные отправители.

Если вы используете другую поверхность продукта для ботов Zalo и проверили рабочее поведение групп, документируйте это отдельно, а не предполагая совпадение с потоком Marketplace-ботов.

Long-polling или webhook

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

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

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

Краткий обзор поддержки см. в разделе Возможности. Примечания ниже добавляют подробности там, где поведению нужен дополнительный контекст.

Текстовые сообщения: полная поддержка с разбиением на фрагменты по 2000 символов.
Обычные URL в тексте: ведут себя как обычный текстовый ввод.
Предпросмотры ссылок / расширенные карточки ссылок: см. статус Marketplace-ботов в разделе Возможности; они не всегда надежно вызывали ответ.
Сообщения с изображениями: см. статус Marketplace-ботов в разделе Возможности; обработка входящих изображений была ненадежной (индикатор набора без финального ответа).
Стикеры: см. статус Marketplace-ботов в разделе Возможности.
Голосовые заметки / аудиофайлы / видео / обычные вложения файлов: см. статус Marketplace-ботов в разделе Возможности.
Неподдерживаемые типы: журналируются (например, сообщения от защищенных пользователей).

Возможности

Эта таблица суммирует текущее поведение ботов Zalo Bot Creator / Marketplace в OpenClaw.

Функция	Статус
Личные сообщения	✅ Поддерживаются
Группы	❌ Недоступны для Marketplace-ботов
Медиа (входящие изображения)	⚠️ Ограничено / проверьте в своей среде
Медиа (исходящие изображения)	⚠️ Не перепроверялось для Marketplace-ботов
Обычные URL в тексте	✅ Поддерживаются
Предпросмотры ссылок	⚠️ Ненадежны для Marketplace-ботов
Реакции	❌ Не поддерживаются
Стикеры	⚠️ Нет ответа агента для Marketplace-ботов
Голосовые заметки / аудио / видео	⚠️ Нет ответа агента для Marketplace-ботов
Вложения файлов	⚠️ Нет ответа агента для Marketplace-ботов
Threads	❌ Не поддерживаются
Опросы	❌ Не поддерживаются
Встроенные команды	❌ Не поддерживаются
Streaming	⚠️ Заблокирован (ограничение 2000 символов)

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

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

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

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

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

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

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

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

Полная конфигурация: Configuration Плоские ключи верхнего уровня (channels.zalo.botToken, channels.zalo.dmPolicy и подобные) — это устаревшее сокращение для одной учетной записи. Для новых конфигураций предпочитайте channels.zalo.accounts.<id>.*. Обе формы все еще документируются здесь, потому что они существуют в схеме. Параметры provider:

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

Параметры нескольких учетных записей:

channels.zalo.accounts.<id>.botToken: токен для учетной записи.
channels.zalo.accounts.<id>.tokenFile: обычный файл токена для учетной записи. Symlink отклоняются.
channels.zalo.accounts.<id>.name: отображаемое имя.
channels.zalo.accounts.<id>.enabled: включить/отключить учетную запись.
channels.zalo.accounts.<id>.dmPolicy: политика личных сообщений для учетной записи.
channels.zalo.accounts.<id>.allowFrom: allowlist для учетной записи.
channels.zalo.accounts.<id>.groupPolicy: групповая политика для учетной записи. Присутствует в config; о текущем поведении Marketplace-ботов см. Возможности и Контроль доступа (группы).
channels.zalo.accounts.<id>.groupAllowFrom: allowlist отправителей группы для учетной записи.
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 прокси для учетной записи.

См. также

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

​Встроенный plugin

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

​Что это такое

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

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

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

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

​Ограничения

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

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

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

​Long-polling или webhook

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

​Возможности

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

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

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

​См. также