--- read_when: - Работа с функциями Zalo или Webhook summary: Статус поддержки, возможности и настройка бота Zalo title: Zalo x-i18n: generated_at: "2026-06-28T22:38:17Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: 6226af1217e1e8b03b485df99f6375872b487f7040c091f2bb2d85e18dec75d0 source_path: channels/zalo.md workflow: 16 --- Статус: экспериментально. Личные сообщения поддерживаются. Раздел [Возможности](#capabilities) ниже отражает текущее поведение 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](/ru/tools/plugin) ## Быстрая настройка (для начинающих) 1. Убедитесь, что plugin Zalo доступен. - Текущие пакетные выпуски OpenClaw уже включают его. - Более старые/пользовательские установки могут добавить его вручную с помощью команд выше. 2. Задайте токен: - Env: `ZALO_BOT_TOKEN=...` - Или config: `channels.zalo.accounts.default.botToken: "..."`. 3. Перезапустите gateway (или завершите настройку). 4. Доступ к личным сообщениям по умолчанию выполняется через pairing; подтвердите код pairing при первом контакте. Минимальная конфигурация: ```json5 { 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; модель никогда не выбирает каналы. - Личные сообщения используют основной сеанс агента. - Раздел [Возможности](#capabilities) ниже показывает текущую поддержку Marketplace-ботов. ## Настройка (быстрый путь) ### 1) Создайте токен бота (Zalo Bot Platform) 1. Перейдите на [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) и войдите в систему. 2. Создайте нового бота и настройте его параметры. 3. Скопируйте полный токен бота (обычно `numeric_id:secret`). Для Marketplace-ботов пригодный для runtime токен может появиться в приветственном сообщении бота после создания. ### 2) Настройте токен (env или config) Пример: ```json5 { channels: { zalo: { enabled: true, accounts: { default: { botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, }, }, } ``` Если позже вы перейдете на поверхность бота Zalo, где доступны группы, можно явно добавить конфигурацию для групп, например `groupPolicy` и `groupAllowFrom`. О текущем поведении Marketplace-ботов см. [Возможности](#capabilities). Вариант env: `ZALO_BOT_TOKEN=...` (работает только для учетной записи по умолчанию). Поддержка нескольких учетных записей: используйте `channels.zalo.accounts` с токенами для каждой учетной записи и необязательным `name`. 3. Перезапустите gateway. Zalo запускается, когда токен найден (env или config). 4. Для доступа к личным сообщениям по умолчанию используется 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 ` - Pairing — обмен токенами по умолчанию. Подробности: [Pairing](/ru/channels/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. ## Поддерживаемые типы сообщений Краткий обзор поддержки см. в разделе [Возможности](#capabilities). Примечания ниже добавляют подробности там, где поведению нужен дополнительный контекст. - **Текстовые сообщения**: полная поддержка с разбиением на фрагменты по 2000 символов. - **Обычные URL в тексте**: ведут себя как обычный текстовый ввод. - **Предпросмотры ссылок / расширенные карточки ссылок**: см. статус Marketplace-ботов в разделе [Возможности](#capabilities); они не всегда надежно вызывали ответ. - **Сообщения с изображениями**: см. статус Marketplace-ботов в разделе [Возможности](#capabilities); обработка входящих изображений была ненадежной (индикатор набора без финального ответа). - **Стикеры**: см. статус Marketplace-ботов в разделе [Возможности](#capabilities). - **Голосовые заметки / аудиофайлы / видео / обычные вложения файлов**: см. статус Marketplace-ботов в разделе [Возможности](#capabilities). - **Неподдерживаемые типы**: журналируются (например, сообщения от защищенных пользователей). ## Возможности Эта таблица суммирует текущее поведение **ботов 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](/ru/gateway/configuration) Плоские ключи верхнего уровня (`channels.zalo.botToken`, `channels.zalo.dmPolicy` и подобные) — это устаревшее сокращение для одной учетной записи. Для новых конфигураций предпочитайте `channels.zalo.accounts..*`. Обе формы все еще документируются здесь, потому что они существуют в схеме. Параметры 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-ботов см. [Возможности](#capabilities) и [Контроль доступа (группы)](#access-control-groups). - `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..botToken`: токен для учетной записи. - `channels.zalo.accounts..tokenFile`: обычный файл токена для учетной записи. Symlink отклоняются. - `channels.zalo.accounts..name`: отображаемое имя. - `channels.zalo.accounts..enabled`: включить/отключить учетную запись. - `channels.zalo.accounts..dmPolicy`: политика личных сообщений для учетной записи. - `channels.zalo.accounts..allowFrom`: allowlist для учетной записи. - `channels.zalo.accounts..groupPolicy`: групповая политика для учетной записи. Присутствует в config; о текущем поведении Marketplace-ботов см. [Возможности](#capabilities) и [Контроль доступа (группы)](#access-control-groups). - `channels.zalo.accounts..groupAllowFrom`: allowlist отправителей группы для учетной записи. - `channels.zalo.accounts..webhookUrl`: URL webhook для учетной записи. - `channels.zalo.accounts..webhookSecret`: секрет webhook для учетной записи. - `channels.zalo.accounts..webhookPath`: путь webhook для учетной записи. - `channels.zalo.accounts..proxy`: URL прокси для учетной записи. ## См. также - [Обзор каналов](/ru/channels) — все поддерживаемые каналы - [Pairing](/ru/channels/pairing) — аутентификация личных сообщений и поток pairing - [Группы](/ru/channels/groups) — поведение группового чата и проверка упоминаний - [Маршрутизация каналов](/ru/channels/channel-routing) — маршрутизация сеансов для сообщений - [Безопасность](/ru/gateway/security) — модель доступа и усиление безопасности