> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Zalo

Статус: экспериментальный. Реализованы как личные сообщения, так и групповые чаты; приведённая ниже таблица [Возможности](#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`
* Подробнее: [Плагины](https://docs2.openclaw.ai/ru/tools/plugin.md)

## Быстрая настройка

1. Создайте токен бота на [https://bot.zaloplatforms.com](https://bot.zaloplatforms.com) (войдите в систему, создайте бота и настройте параметры). Токен — `numeric_id:secret`; для ботов Marketplace пригодный для выполнения токен может содержаться в приветственном сообщении бота.
2. Укажите токен либо в переменной окружения `ZALO_BOT_TOKEN=...` (только для учётной записи по умолчанию), либо в конфигурации.
3. Перезапустите Gateway.
4. При первом обращении в личных сообщениях подтвердите код сопряжения (политика личных сообщений по умолчанию — сопряжение).

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}
```

Несколько учётных записей: добавьте дополнительные записи в `channels.zalo.accounts.<id>`, указав для каждой собственные `botToken`/`name`. `channels.zalo.botToken` (плоская форма без `accounts`) — устаревшая сокращённая запись для одной учётной записи; для новых конфигураций предпочитайте `accounts.<id>.*`.

## Что это такое

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 <CODE>`
  * Подробнее: [Сопряжение](https://docs2.openclaw.ai/ru/channels/pairing.md)
* `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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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-адреса); увеличьте интервал и повторите попытку

## Справочник по конфигурации

Полная конфигурация: [Конфигурация](https://docs2.openclaw.ai/ru/gateway/configuration.md)

| Параметр | Описание | По умолчанию |
| - | - | - |
| `channels.zalo.enabled` | Включить или отключить запуск канала | `true` |
| `channels.zalo.accounts.<id>.botToken` | Токен бота из Zalo Bot Platform | - |
| `channels.zalo.accounts.<id>.tokenFile` | Читать токен из файла (символические ссылки отклоняются) | - |
| `channels.zalo.accounts.<id>.name` | Отображаемое имя | - |
| `channels.zalo.accounts.<id>.enabled` | Включить или отключить эту учётную запись | `true` |
| `channels.zalo.accounts.<id>.dmPolicy` | Политика личных сообщений для отдельной учётной записи | `pairing` |
| `channels.zalo.accounts.<id>.allowFrom` | Список разрешённых идентификаторов пользователей для личных сообщений | - |
| `channels.zalo.accounts.<id>.groupPolicy` | Групповая политика для отдельной учётной записи | см. [Группы](#groups) |
| `channels.zalo.accounts.<id>.groupAllowFrom` | Список разрешённых отправителей в группах; если не задан, используется `allowFrom` | - |
| `channels.zalo.accounts.<id>.mediaMaxMb` | Ограничение размера входящих/исходящих медиафайлов (МБ) | `5` |
| `channels.zalo.accounts.<id>.webhookUrl` | Включить режим Webhook (требуется HTTPS) | - |
| `channels.zalo.accounts.<id>.webhookSecret` | Секрет Webhook (8–256 символов) | - |
| `channels.zalo.accounts.<id>.webhookPath` | Путь Webhook на HTTP-сервере Gateway | путь URL Webhook |
| `channels.zalo.accounts.<id>.proxy` | URL прокси для запросов API | - |
| `channels.zalo.accounts.<id>.responsePrefix` | Переопределение префикса исходящего ответа | - |
| `channels.zalo.defaultAccount` | Учётная запись по умолчанию, если настроено несколько | `default` |

`channels.zalo.botToken`, `channels.zalo.dmPolicy` и другие плоские ключи верхнего уровня являются устаревшей сокращённой записью для одной учётной записи, соответствующей указанным выше полям; поддерживаются обе формы.

Параметр окружения: `ZALO_BOT_TOKEN=...` задаёт токен только для учётной записи по умолчанию.

## Связанные материалы

* [Обзор каналов](https://docs2.openclaw.ai/ru/channels.md) — все поддерживаемые каналы
* [Сопряжение](https://docs2.openclaw.ai/ru/channels/pairing.md) — аутентификация в личных сообщениях и процесс сопряжения
* [Группы](https://docs2.openclaw.ai/ru/channels/groups.md) — поведение групповых чатов и активация по упоминанию
* [Маршрутизация каналов](https://docs2.openclaw.ai/ru/channels/channel-routing.md) — маршрутизация сеансов для сообщений
* [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md) — модель доступа и усиление защиты