Regional platforms

Zalo

Статус: експериментальний. DM підтримуються. Розділ Можливості нижче відображає поточну поведінку ботів Marketplace.

Вбудований Plugin

Zalo постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні пакетовані збірки не потребують окремого встановлення.

Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Zalo, установіть npm-пакет напряму:

Установити через CLI: openclaw plugins install @openclaw/zalo
Закріплена версія: openclaw plugins install @openclaw/[email protected]
Або з checkout вихідного коду: openclaw plugins install ./path/to/local/zalo-plugin
Докладніше: Plugins

Швидке налаштування (для початківців)

Переконайтеся, що Plugin Zalo доступний.
- Поточні пакетовані випуски OpenClaw уже містять його.
- Старіші/власні встановлення можуть додати його вручну командами вище.
Задайте токен:
- Env: ZALO_BOT_TOKEN=...
- Або config: channels.zalo.accounts.default.botToken: "...".
Перезапустіть Gateway (або завершіть налаштування).
Доступ до DM за замовчуванням працює через pairing; підтвердьте код pairing під час першого контакту.

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

{
  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; модель ніколи не вибирає канали.
DM спільно використовують основну сесію агента.
Розділ Можливості нижче показує поточну підтримку ботів Marketplace.

Налаштування (швидкий шлях)

1) Створіть токен бота (Zalo Bot Platform)

Перейдіть на https://bot.zaloplatforms.com і ввійдіть.
Створіть нового бота й налаштуйте його параметри.
Скопіюйте повний токен бота (зазвичай numeric_id:secret). Для ботів Marketplace придатний для виконання токен може з'явитися у привітальному повідомленні бота після створення.

2) Налаштуйте токен (env або config)

Приклад:

{
  channels: {
    zalo: {
      enabled: true,
      accounts: {
        default: {
          botToken: "12345689:abc-xyz",
          dmPolicy: "pairing",
        },
      },
    },
  },
}

Якщо згодом ви перейдете на поверхню бота Zalo, де доступні групи, можна явно додати групову конфігурацію, як-от groupPolicy і groupAllowFrom. Поточну поведінку ботів Marketplace див. у Можливостях.

Опція env: ZALO_BOT_TOKEN=... (працює лише для облікового запису за замовчуванням).

Підтримка кількох облікових записів: використовуйте channels.zalo.accounts із токенами для кожного облікового запису та необов'язковим name.

Перезапустіть Gateway. Zalo запускається, коли токен визначено (env або config).
Доступ до DM за замовчуванням працює через pairing. Підтвердьте код, коли з ботом уперше зв'яжуться.

Як це працює (поведінка)

Вхідні повідомлення нормалізуються у спільний envelope каналу із заповнювачами медіа.
Відповіді завжди маршрутизуються назад у той самий чат Zalo.
За замовчуванням використовується long-polling; режим webhook доступний із channels.zalo.webhookUrl.

Обмеження

Вихідний текст розбивається на фрагменти по 2000 символів (обмеження Zalo API).
Завантаження/вивантаження медіа обмежені channels.zalo.mediaMaxMb (за замовчуванням 5).
Streaming за замовчуванням заблокований, бо обмеження у 2000 символів робить streaming менш корисним.

Контроль доступу (DM)

Доступ до DM

За замовчуванням: channels.zalo.dmPolicy = "pairing". Невідомі відправники отримують код pairing; повідомлення ігноруються, доки їх не підтвердять (коди спливають через 1 годину).
Підтвердьте через:
- openclaw pairing list zalo
- openclaw pairing approve zalo <CODE>
Pairing — це типовий обмін токеном. Докладніше: Pairing
channels.zalo.allowFrom приймає числові ID користувачів (пошук за іменем користувача недоступний).

Контроль доступу (групи)

Для ботів Zalo Bot Creator / Marketplace підтримка груп на практиці була недоступна, бо бота взагалі не можна було додати до групи.

Це означає, що наведені нижче ключі конфігурації, пов'язані з групами, існують у схемі, але не були придатні для використання з ботами Marketplace:

channels.zalo.groupPolicy керує обробкою вхідних повідомлень у групах: open | allowlist | disabled.
channels.zalo.groupAllowFrom обмежує, які ID відправників можуть запускати бота в групах.
Якщо groupAllowFrom не задано, Zalo повертається до allowFrom для перевірок відправника.
Примітка щодо виконання: якщо channels.zalo повністю відсутній, runtime все одно повертається до groupPolicy="allowlist" для безпеки.

Значення групової політики (коли груповий доступ доступний на поверхні вашого бота):

groupPolicy: "disabled" — блокує всі групові повідомлення.
groupPolicy: "open" — дозволяє будь-якого учасника групи (з gate за згадкою).
groupPolicy: "allowlist" — типовий fail-closed режим; приймаються лише дозволені відправники.

Якщо ви використовуєте іншу продуктову поверхню бота 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) ігноруються протягом короткого вікна replay.
- Burst-трафік обмежується за частотою для кожного шляху/джерела й може повертати HTTP 429.

Примітка: getUpdates (polling) і webhook є взаємовиключними згідно з документацією Zalo API.

Підтримувані типи повідомлень

Швидкий знімок підтримки див. у Можливостях. Примітки нижче додають деталі там, де поведінка потребує додаткового контексту.

Текстові повідомлення: повна підтримка з розбиттям на фрагменти по 2000 символів.
Звичайні URL у тексті: поводяться як звичайне текстове введення.
Попередні перегляди посилань / насичені картки посилань: див. статус ботів Marketplace у Можливостях; вони не запускали відповідь надійно.
Повідомлення із зображеннями: див. статус ботів Marketplace у Можливостях; обробка вхідних зображень була ненадійною (індикатор набору без фінальної відповіді).
Стікери: див. статус ботів Marketplace у Можливостях.
Голосові нотатки / аудіофайли / відео / звичайні файлові вкладення: див. статус ботів Marketplace у Можливостях.
Непідтримувані типи: логуються (наприклад, повідомлення від захищених користувачів).

Можливості

Ця таблиця підсумовує поточну поведінку ботів Zalo Bot Creator / Marketplace в OpenClaw.

Функція	Статус
Прямі повідомлення	✅ Підтримується
Групи	❌ Недоступні для ботів Marketplace
Медіа (вхідні зображення)	⚠️ Обмежено / перевірте у своєму середовищі
Медіа (вихідні зображення)	⚠️ Не тестувалося повторно для ботів Marketplace
Звичайні URL у тексті	✅ Підтримується
Попередні перегляди посилань	⚠️ Ненадійні для ботів Marketplace
Реакції	❌ Не підтримуються
Стікери	⚠️ Немає відповіді агента для ботів Marketplace
Голосові нотатки / аудіо / відео	⚠️ Немає відповіді агента для ботів Marketplace
Файлові вкладення	⚠️ Немає відповіді агента для ботів Marketplace
Threads	❌ Не підтримуються
Опитування	❌ Не підтримуються
Нативні команди	❌ Не підтримуються
Streaming	⚠️ Заблоковано (обмеження 2000 символів)

Цілі доставки (CLI/cron)

Використовуйте chat id як ціль.
Приклад: 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

Плоскі ключі верхнього рівня (channels.zalo.botToken, channels.zalo.dmPolicy тощо) — це застарочений скорочений запис для одного облікового запису. Для нових конфігурацій віддавайте перевагу channels.zalo.accounts.<id>.*. Обидві форми все ще задокументовані тут, бо вони існують у схемі.

Опції провайдера:

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 для DM (ID користувачів). open вимагає "*". Майстер запитає числові ID.
channels.zalo.groupPolicy: open | allowlist | disabled (за замовчуванням: allowlist). Присутній у config; поточну поведінку ботів Marketplace див. у Можливостях і Контролі доступу (групи).
channels.zalo.groupAllowFrom: allowlist відправників у групах (ID користувачів). Повертається до 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 proxy для 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: політика DM для кожного облікового запису.
channels.zalo.accounts.<id>.allowFrom: allowlist для кожного облікового запису.
channels.zalo.accounts.<id>.groupPolicy: групова політика для кожного облікового запису. Присутня в config; поточну поведінку ботів Marketplace див. у Можливостях і Контролі доступу (групи).
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 proxy для кожного облікового запису.

Пов'язане

Огляд каналів — усі підтримувані канали
Pairing — автентифікація DM і потік pairing
Групи — поведінка групових чатів і gate за згадкою
Маршрутизація каналів — маршрутизація сесій для повідомлень
Безпека — модель доступу й посилення захисту

# Вбудований Plugin

# Швидке налаштування (для початківців)

# Що це таке

# Налаштування (швидкий шлях)

# 1) Створіть токен бота (Zalo Bot Platform)

# 2) Налаштуйте токен (env або config)

# Як це працює (поведінка)

# Обмеження

# Контроль доступу (DM)

# Доступ до DM

# Контроль доступу (групи)

# Long-polling проти webhook

# Підтримувані типи повідомлень

# Можливості

# Цілі доставки (CLI/cron)

# Усунення несправностей

# Довідник конфігурації (Zalo)

# Пов'язане