​

Zalo (Bot API)

​

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

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

​

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

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

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

​

Что это такое

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

​

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

​

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",
    },
  },
}

3. Перезапустите Gateway (шлюз). Zalo запускается, когда токен определен (через переменные окружения или конфиг).
4. Доступ к личным сообщениям по умолчанию — через сопряжение. Подтвердите код при первом обращении к боту.

​

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

• Входящие сообщения нормализуются в общий конверт канала с плейсхолдерами медиа.
• Ответы всегда маршрутизируются обратно в тот же чат 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>
• Сопряжение — стандартный обмен токенами. Подробности: Pairing
• channels.zalo.allowFrom принимает числовые идентификаторы пользователей (поиск по имени пользователя недоступен).

​

Long-polling vs вебхук

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

​

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

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

​

Возможности

​

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

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

​

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

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

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

​

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

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