---
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.<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>`
  - Подробнее: [Сопряжение](/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.<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=...` задаёт токен только для учётной записи по умолчанию.

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

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