> ## 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) ниже отражает текущее поведение 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 <CODE>`
* 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.<id>.*`. Обе формы все еще документируются здесь, потому что они существуют в схеме.

Параметры 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.<id>.botToken`: токен для учетной записи.
* `channels.zalo.accounts.<id>.tokenFile`: обычный файл токена для учетной записи. Symlink отклоняются.
* `channels.zalo.accounts.<id>.name`: отображаемое имя.
* `channels.zalo.accounts.<id>.enabled`: включить/отключить учетную запись.
* `channels.zalo.accounts.<id>.dmPolicy`: политика личных сообщений для учетной записи.
* `channels.zalo.accounts.<id>.allowFrom`: allowlist для учетной записи.
* `channels.zalo.accounts.<id>.groupPolicy`: групповая политика для учетной записи. Присутствует в config; о текущем поведении Marketplace-ботов см. [Возможности](#capabilities) и [Контроль доступа (группы)](#access-control-groups).
* `channels.zalo.accounts.<id>.groupAllowFrom`: allowlist отправителей группы для учетной записи.
* `channels.zalo.accounts.<id>.webhookUrl`: URL webhook для учетной записи.
* `channels.zalo.accounts.<id>.webhookSecret`: секрет webhook для учетной записи.
* `channels.zalo.accounts.<id>.webhookPath`: путь webhook для учетной записи.
* `channels.zalo.accounts.<id>.proxy`: URL прокси для учетной записи.

## См. также

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