Zalo

​

Вбудований плагін

• Установлення: openclaw plugins install @openclaw/zalo
• Закріплена версія: openclaw plugins install @openclaw/zalo@2026.6.11
• З локальної робочої копії: openclaw plugins install ./path/to/local/zalo-plugin
• Докладніше: Плагіни

​

Швидке налаштування

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

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

​

Що це таке

​

Як це працює

• Вхідні повідомлення нормалізуються в спільний конверт каналу із заповнювачами для медіафайлів.
• Відповіді завжди маршрутизуються назад до того самого чату Zalo; відповідь із цитуванням не використовується (replyToMode завжди вимкнено).
• За замовчуванням використовується тривале опитування (getUpdates); режим Webhook доступний через channels.zalo.webhookUrl.
• У групах для запуску бота потрібна @згадка; це не можна налаштувати окремо для каналу.

​

Обмеження

​

Керування доступом

​

Прямі повідомлення

• channels.zalo.dmPolicy: pairing (за замовчуванням) | allowlist | open | disabled.
• Сполучення: невідомі відправники отримують код сполучення; повідомлення ігноруються до підтвердження. Термін дії кодів спливає через 1 годину.
  • openclaw pairing list zalo
  • openclaw pairing approve zalo <CODE>
  • Докладніше: Сполучення
• channels.zalo.allowFrom приймає числові ідентифікатори користувачів Zalo (пошук за іменем користувача не підтримується). Для open потрібно вказати "*".

​

Групи

• 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).
  • Відповідно до документації Zalo API, опитування getUpdates і Webhook є взаємовиключними.

​

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

• Текст: повна підтримка з поділом на фрагменти по 2000 символів.
• Медіафайли: вхідні й вихідні, з обмеженням mediaMaxMb.
• Реакції, гілки, опитування, вбудовані команди: не підтримуються плагіном.
• Потокове передавання: плагін заявляє можливість блокового потокового передавання, але Zalo не має спеціальних параметрів налаштування вихідної черги чи обʼєднання тексту (на відміну від деяких інших регіональних каналів); якщо це важливо для вашого сценарію використання, перевірте поточну поведінку у своєму середовищі.

​

Можливості

​

Цілі доставлення (CLI/cron)

openclaw message send --channel zalo --target 123456789 --message "hi"

​

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

• Перевірте токен: openclaw channels status --probe
• Переконайтеся, що відправника схвалено (через сполучення або allowFrom)
• Перевірте журнали Gateway: openclaw logs --follow

• Переконайтеся, що URL-адреса Webhook використовує HTTPS
• Переконайтеся, що секрет містить 8–256 символів
• Переконайтеся, що кінцева точка HTTP-сервера Gateway доступна за налаштованим шляхом
• Переконайтеся, що опитування getUpdates не виконується одночасно (вони є взаємовиключними)
• Сплеск запитів може призвести до відповіді HTTP 429 (120 запитів / 60 с для кожної комбінації шляху й IP-адреси); збільште інтервал і повторіть спробу

​

Довідник конфігурації

​

Повʼязані матеріали

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