> ## Documentation Index > Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt > Use this file to discover all available pages before exploring further. # Zalo # Zalo (Bot API) Статус: экспериментальный. Только личные сообщения; группы появятся в ближайшее время согласно документации Zalo. ## Требуется плагин Zalo поставляется в виде плагина и не входит в базовую установку. * Установка через CLI: `openclaw plugins install @openclaw/zalo` * Или выберите **Zalo** во время онбординга и подтвердите запрос на установку * Подробности: [Plugins](/tools/plugin) ## Быстрая настройка (для начинающих) 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. Доступ к личным сообщениям по умолчанию — через сопряжение; подтвердите код сопряжения при первом контакте. Минимальный конфиг: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, } ``` ## Что это такое Zalo — ориентированное на Вьетнам приложение для обмена сообщениями; его Bot API позволяет Gateway (шлюзу) запускать бота для диалогов 1:1. Хорошо подходит для поддержки или уведомлений, когда требуется детерминированная маршрутизация обратно в Zalo. * Канал Zalo Bot API, принадлежащий Gateway (шлюзу). * Детерминированная маршрутизация: ответы всегда возвращаются в Zalo; модель не выбирает каналы. * ЛС разделяют основную сессию агента. * Группы пока не поддерживаются (в документации Zalo указано «coming soon»). ## Настройка (быстрый путь) ### 1. Создайте токен бота (Zalo Bot Platform) 1. Перейдите на [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) и войдите. 2. Создайте нового бота и настройте его параметры. 3. Скопируйте токен бота (формат: `12345689:abc-xyz`). ### 2) Настройте токен (переменные окружения или конфиг) Пример: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { channels: { zalo: { enabled: true, botToken: "12345689:abc-xyz", dmPolicy: "pairing", }, }, } ``` Вариант через переменные окружения: `ZALO_BOT_TOKEN=...` (работает только для учетной записи по умолчанию). Поддержка нескольких учетных записей: используйте `channels.zalo.accounts` с токенами для каждой учетной записи и необязательным `name`. 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 ` * Сопряжение — стандартный обмен токенами. Подробности: [Pairing](/channels/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 вебхука). **Примечание:** getUpdates (polling) и вебхук взаимоисключающи согласно документации API Zalo. ## Поддерживаемые типы сообщений * **Текстовые сообщения**: полная поддержка с разбиением по 2000 символов. * **Изображения**: загрузка и обработка входящих изображений; отправка изображений через `sendPhoto`. * **Стикеры**: логируются, но не полностью обрабатываются (без ответа агента). * **Неподдерживаемые типы**: логируются (например, сообщения от защищенных пользователей). ## Возможности | Функция | Статус | | ---------------- | ----------------------------- | | Прямые сообщения | ✅ Поддерживаются | | Группы | ❌ Скоро (согласно докам Zalo) | | Медиа (изображ.) | ✅ Поддерживаются | | Реакции | ❌ Не поддерживаются | | Потоки | ❌ Не поддерживаются | | Опросы | ❌ Не поддерживаются | | Родные команды | ❌ Не поддерживаются | | Вещание | ⚠️ Заблокирован (лимит 2000) | ## Цели доставки (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) Полная конфигурация: [Configuration](/gateway/configuration) Параметры провайдера: * `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..botToken`: токен для конкретной учетной записи. * `channels.zalo.accounts..tokenFile`: файл токена для конкретной учетной записи. * `channels.zalo.accounts..name`: отображаемое имя. * `channels.zalo.accounts..enabled`: включить/отключить учетную запись. * `channels.zalo.accounts..dmPolicy`: политика личных сообщений для учетной записи. * `channels.zalo.accounts..allowFrom`: список разрешённых для учетной записи. * `channels.zalo.accounts..webhookUrl`: URL вебхука для учетной записи. * `channels.zalo.accounts..webhookSecret`: секрет вебхука для учетной записи. * `channels.zalo.accounts..webhookPath`: путь вебхука для учетной записи. * `channels.zalo.accounts..proxy`: URL прокси для учетной записи.