--- read_when: - Работа с функциями Zalo или вебхуками summary: Статус поддержки, возможности и настройка бота Zalo title: Zalo x-i18n: generated_at: "2026-07-13T17:54:54Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 36e624f1abeeaee56d7376b9df9209f8e7614ade2f089bcecd76ff746b942765 source_path: channels/zalo.md workflow: 16 --- Статус: экспериментальный. Реализованы как личные сообщения, так и групповые чаты; приведённая ниже таблица [Возможности](#capabilities) отражает поведение, проверенное для ботов 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` - Подробнее: [Плагины](/ru/tools/plugin) ## Быстрая настройка 1. Создайте токен бота на [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) (войдите в систему, создайте бота и настройте параметры). Токен — `numeric_id:secret`; для ботов Marketplace пригодный для выполнения токен может содержаться в приветственном сообщении бота. 2. Укажите токен либо в переменной окружения `ZALO_BOT_TOKEN=...` (только для учётной записи по умолчанию), либо в конфигурации. 3. Перезапустите Gateway. 4. При первом обращении в личных сообщениях подтвердите код сопряжения (политика личных сообщений по умолчанию — сопряжение). Минимальная конфигурация: ```json5 { channels: { zalo: { enabled: true, accounts: { default: { botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, }, }, } ``` Несколько учётных записей: добавьте дополнительные записи в `channels.zalo.accounts.`, указав для каждой собственные `botToken`/`name`. `channels.zalo.botToken` (плоская форма без `accounts`) — устаревшая сокращённая запись для одной учётной записи; для новых конфигураций предпочитайте `accounts..*`. ## Что это такое Zalo — ориентированное на Вьетнам приложение для обмена сообщениями. Его Bot API позволяет Gateway запускать бота как для личных бесед, так и для групповых чатов с детерминированной маршрутизацией ответов обратно в Zalo (модель никогда не выбирает каналы). Эта страница посвящена **ботам Zalo Bot Creator / Marketplace**. **Боты Zalo Official Account (OA)** относятся к другой части продукта и могут вести себя иначе; на этой странице они не рассматриваются. ## Принцип работы - Входящие сообщения нормализуются в общий конверт канала с заполнителями для медиафайлов. - Ответы всегда направляются обратно в тот же чат Zalo; ответы с цитированием не используются (`replyToMode` всегда отключён). - По умолчанию используется длительный опрос (`getUpdates`); режим Webhook доступен через `channels.zalo.webhookUrl`. - В группах для активации бота требуется @упоминание; это нельзя настроить отдельно для канала. ## Ограничения | Ограничение | Значение | | ------------------------------ | ----------------------------------------------------------------------------- | | Размер фрагмента исходящего текста | 2000 символов (ограничение API Zalo) | | Размер медиафайла (входящего/исходящего) | `channels.zalo.mediaMaxMb`, по умолчанию `5` МБ | | Тело запроса Webhook | 1 МБ, тайм-аут чтения 30 с | | Ограничение частоты запросов Webhook | 120 запросов / 60 с на комбинацию пути и IP-адреса клиента, затем HTTP 429 | | Окно обнаружения повторяющихся событий Webhook | 5 минут (ключ составляется из пути, учётной записи, имени события, чата, отправителя и идентификатора сообщения) | ## Управление доступом ### Личные сообщения - `channels.zalo.dmPolicy`: `pairing` (по умолчанию) | `allowlist` | `open` | `disabled`. - Сопряжение: неизвестные отправители получают код сопряжения; сообщения игнорируются до его подтверждения. Срок действия кодов истекает через 1 час. - `openclaw pairing list zalo` - `openclaw pairing approve zalo ` - Подробнее: [Сопряжение](/ru/channels/pairing) - `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 не предоставляет отдельных параметров настройки очереди исходящих сообщений или объединения текста (в отличие от некоторых других региональных каналов); если это важно для вашего сценария, проверьте текущее поведение в своей среде. ## Возможности | Функция | Статус | | ------------------------ | --------------------------------- | | Личные сообщения | Поддерживаются | | Группы | Поддерживаются (требуется упоминание) | | Медиафайлы (входящие/исходящие) | Поддерживаются, с ограничением `mediaMaxMb` | | Реакции | Не поддерживаются | | Ветки | Не поддерживаются | | Опросы | Не поддерживаются | | Нативные команды | Не поддерживаются | | Ответ на сообщение / цитирование | Не используется (всегда отключено) | ## Цели доставки (CLI/Cron) Используйте идентификатор чата в качестве цели: ```bash 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-адреса); увеличьте интервал и повторите попытку ## Справочник по конфигурации Полная конфигурация: [Конфигурация](/ru/gateway/configuration) | Параметр | Описание | По умолчанию | | -------------------------------------------- | ------------------------------------------------- | --------------------- | | `channels.zalo.enabled` | Включить или отключить запуск канала | `true` | | `channels.zalo.accounts..botToken` | Токен бота из Zalo Bot Platform | - | | `channels.zalo.accounts..tokenFile` | Читать токен из файла (символические ссылки отклоняются) | - | | `channels.zalo.accounts..name` | Отображаемое имя | - | | `channels.zalo.accounts..enabled` | Включить или отключить эту учётную запись | `true` | | `channels.zalo.accounts..dmPolicy` | Политика личных сообщений для отдельной учётной записи | `pairing` | | `channels.zalo.accounts..allowFrom` | Список разрешённых идентификаторов пользователей для личных сообщений | - | | `channels.zalo.accounts..groupPolicy` | Групповая политика для отдельной учётной записи | см. [Группы](#groups) | | `channels.zalo.accounts..groupAllowFrom` | Список разрешённых отправителей в группах; если не задан, используется `allowFrom` | - | | `channels.zalo.accounts..mediaMaxMb` | Ограничение размера входящих/исходящих медиафайлов (МБ) | `5` | | `channels.zalo.accounts..webhookUrl` | Включить режим Webhook (требуется HTTPS) | - | | `channels.zalo.accounts..webhookSecret` | Секрет Webhook (8–256 символов) | - | | `channels.zalo.accounts..webhookPath` | Путь Webhook на HTTP-сервере Gateway | путь URL Webhook | | `channels.zalo.accounts..proxy` | URL прокси для запросов API | - | | `channels.zalo.accounts..responsePrefix` | Переопределение префикса исходящего ответа | - | | `channels.zalo.defaultAccount` | Учётная запись по умолчанию, если настроено несколько | `default` | `channels.zalo.botToken`, `channels.zalo.dmPolicy` и другие плоские ключи верхнего уровня являются устаревшей сокращённой записью для одной учётной записи, соответствующей указанным выше полям; поддерживаются обе формы. Параметр окружения: `ZALO_BOT_TOKEN=...` задаёт токен только для учётной записи по умолчанию. ## Связанные материалы - [Обзор каналов](/ru/channels) — все поддерживаемые каналы - [Сопряжение](/ru/channels/pairing) — аутентификация в личных сообщениях и процесс сопряжения - [Группы](/ru/channels/groups) — поведение групповых чатов и активация по упоминанию - [Маршрутизация каналов](/ru/channels/channel-routing) — маршрутизация сеансов для сообщений - [Безопасность](/ru/gateway/security) — модель доступа и усиление защиты