> ## 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 ClawBot

OpenClaw підключається до Zalo ClawBot через зазначений у каталозі зовнішній
Plugin `@zalo-platforms/openclaw-zaloclawbot`. Вхід використовує QR-код Zalo Mini App.

## Сумісність

| Версія Plugin | Версія OpenClaw | npm dist-tag | Стан            |
| ------------- | --------------- | ------------ | --------------- |
| 0.1.x         | >=2026.4.10     | `latest`     | Активний / бета |

## Передумови

* Node.js **>= 22**
* [OpenClaw](https://docs.openclaw.ai/install) має бути встановлено (CLI `openclaw` доступний).
* Обліковий запис Zalo на мобільному пристрої для сканування QR-коду входу.

## Встановлення через onboard (рекомендовано)

Запустіть майстер початкового налаштування OpenClaw і виберіть **Zalo ClawBot** у меню каналів:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard
```

Майстер встановлює Plugin з офіційного каталогу (з перевіркою цілісності), показує QR-код входу прямо в терміналі та завершує налаштування каналу після того, як ви проскануєте його застосунком Zalo. Додаткові команди не потрібні.

## Ручне встановлення

Щоб додати канал до вже налаштованого gateway, виконайте такі кроки:

### 1. Встановіть Plugin

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install "@zalo-platforms/openclaw-zaloclawbot@0.1.4"
```

Використовуйте точну зафіксовану версію, показану вище (вона відповідає запису в офіційному каталозі), щоб OpenClaw під час встановлення перевірив пакет за хешем цілісності каталогу.

### 2. Увімкніть Plugin у конфігурації

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw config set plugins.entries.openclaw-zaloclawbot.enabled true
```

### 3. Згенеруйте QR-код і увійдіть

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels login --channel openclaw-zaloclawbot
```

Проскануйте QR-код, показаний у терміналі, за допомогою мобільного застосунку Zalo, прийміть Умови використання всередині Zalo Mini App і авторизуйте сеанс.

### 4. Перезапустіть gateway

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway restart
```

***

## Як це працює

На відміну від стандартного каналу Zalo для розробників, який вимагає зареєструвати власний Zalo Official Account (OA) і вставити статичні облікові дані розробника, Zalo ClawBot працює як **персональний асистент, прив’язаний до власника**, використовуючи спільну офіційну інфраструктуру:

1. **Безпечне початкове налаштування:** QR-код веде до захищеного Zalo Mini App, який прив’язує щойно створеного приватного бота під спільним офіційним OA безпосередньо до вашого Zalo User ID.
2. **Приватність із прив’язкою до власника:** За задумом бот обмежений спілкуванням *лише* зі своїм власником. Повідомлення від інших користувачів відкидаються на рівні платформи, що робить підключення приватним і безпечним.
3. **Офіційний шлях API:** Plugin використовує API Zalo Bot Platform замість
   автоматизації браузера або веб-сеансу.

## Під капотом

Plugin Zalo ClawBot взаємодіє з API Zalo через постійний цикл отримання повідомлень методом long-polling. Щоб підтримувати чисте й легке середовище виконання:

* Підключення long-poll використовують endpoint `getUpdates`.
* Webhook за замовчуванням вимкнено для локальних запусків gateway у настільному застосунку або терміналі.
* Повідомлення обробляються на боці клієнта й безпосередньо зіставляються з вашим локальним середовищем виконання агента.

Зовнішній Plugin керує обліковими даними бота в каталозі стану OpenClaw.
Вважайте цей каталог конфіденційним і застосовуйте до нього ту саму політику
контролю доступу та резервного копіювання, що й до решти стану OpenClaw.

***

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

* **Час очікування входу через QR вичерпано:** Токен входу (`zbsk`) з міркувань безпеки спливає через 5 хвилин. Якщо QR-код спливе до того, як ви його проскануєте, просто повторно запустіть команду входу, щоб згенерувати новий.
* **Gateway не завантажується:** Переконайтеся, що версія вашого хоста OpenClaw — `2026.4.10` або новіша. Старіші версії не підтримують журнал встановлення зовнішніх npm-Plugin.