> ## 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 personal
Статус: експериментально. Ця інтеграція автоматизує **особистий обліковий запис Zalo** через нативний `zca-js` усередині OpenClaw.
Це неофіційна інтеграція, яка може призвести до призупинення або блокування облікового запису. Використовуйте на власний ризик.
## Вбудований Plugin
Zalo Personal постачається як вбудований Plugin у поточних випусках OpenClaw, тому звичайні
пакетовані збірки не потребують окремого встановлення.
Якщо ви використовуєте старішу збірку або власне встановлення, яке виключає Zalo Personal,
установіть npm-пакет напряму:
* Встановити через CLI: `openclaw plugins install @openclaw/zalouser`
* Закріплена версія: `openclaw plugins install @openclaw/zalouser@2026.5.2`
* Або з checkout вихідного коду: `openclaw plugins install ./path/to/local/zalouser-plugin`
* Докладніше: [Plugins](/uk/tools/plugin)
Зовнішній CLI-бінарник `zca`/`openzca` не потрібен.
## Швидке налаштування (для початківців)
1. Переконайтеся, що Plugin Zalo Personal доступний.
* Поточні пакетовані випуски OpenClaw уже містять його.
* Старіші/власні встановлення можуть додати його вручну командами вище.
2. Увійдіть (QR, на машині Gateway):
* `openclaw channels login --channel zalouser`
* Відскануйте QR-код мобільним застосунком Zalo.
3. Увімкніть канал:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
zalouser: {
enabled: true,
dmPolicy: "pairing",
},
},
}
```
4. Перезапустіть Gateway (або завершіть налаштування).
5. Доступ до DM за замовчуванням використовує сполучення; підтвердьте код сполучення під час першого контакту.
## Що це таке
* Повністю працює в процесі через `zca-js`.
* Використовує нативні слухачі подій для отримання вхідних повідомлень.
* Надсилає відповіді напряму через JS API (текст/медіа/посилання).
* Призначено для сценаріїв використання "особистого облікового запису", де Zalo Bot API недоступний.
## Найменування
Ідентифікатор каналу — `zalouser`, щоб явно показати, що це автоматизує **особистий обліковий запис користувача Zalo** (неофіційно). Ми залишаємо `zalo` зарезервованим для потенційної майбутньої офіційної інтеграції Zalo API.
## Пошук ідентифікаторів (каталог)
Використовуйте CLI каталогу, щоб знаходити співрозмовників/групи та їхні ідентифікатори:
```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"
```
## Обмеження
* Вихідний текст розбивається на фрагменти приблизно по 2000 символів (обмеження клієнта Zalo).
* Потокове передавання за замовчуванням заблоковане.
## Контроль доступу (DM)
`channels.zalouser.dmPolicy` підтримує: `pairing | allowlist | open | disabled` (за замовчуванням: `pairing`).
`channels.zalouser.allowFrom` має використовувати стабільні ідентифікатори користувачів Zalo. Він також може посилатися на статичні групи доступу відправників (`accessGroup:`). Під час інтерактивного налаштування введені імена можна перетворити на ідентифікатори за допомогою внутрішньопроцесного пошуку контактів Plugin.
Якщо сире ім’я залишається в конфігурації, під час запуску воно перетворюється лише коли ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`. Без цієї явної згоди перевірки відправника під час виконання працюють лише за ідентифікаторами, а сирі імена ігноруються для авторизації.
Підтвердьте через:
* `openclaw pairing list zalouser`
* `openclaw pairing approve zalouser `
## Доступ до груп (необов’язково)
* За замовчуванням: `channels.zalouser.groupPolicy = "open"` (групи дозволені). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, коли воно не задане.
* Обмежити списком дозволених:
* `channels.zalouser.groupPolicy = "allowlist"`
* `channels.zalouser.groups` (ключами мають бути стабільні ідентифікатори груп; імена перетворюються на ідентифікатори під час запуску лише коли ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`)
* `channels.zalouser.groupAllowFrom` (керує тим, які відправники в дозволених групах можуть запускати бота; на статичні групи доступу відправників можна посилатися через `accessGroup:`)
* Заблокувати всі групи: `channels.zalouser.groupPolicy = "disabled"`.
* Майстер налаштування може запитувати списки дозволених груп.
* Під час запуску OpenClaw перетворює імена груп/користувачів у списках дозволених на ідентифікатори та журналює зіставлення лише коли ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`.
* Зіставлення списку дозволених груп за замовчуванням працює лише за ідентифікаторами. Нерозпізнані імена ігноруються для авторизації, якщо не ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`.
* `channels.zalouser.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який повторно вмикає змінне перетворення імен під час запуску та зіставлення назв груп під час виконання.
* Якщо `groupAllowFrom` не задано, під час виконання перевірки відправників у групах використовують `allowFrom` як резервний варіант.
* Перевірки відправників застосовуються як до звичайних групових повідомлень, так і до керівних команд (наприклад, `/new`, `/reset`).
Приклад:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groupAllowFrom: ["1471383327500481391"],
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
### Обмеження групових згадок
* `channels.zalouser.groups..requireMention` керує тим, чи потребують групові відповіді згадки.
* Порядок розв’язання: точний id/назва групи -> нормалізований slug групи -> `*` -> типове значення (`true`).
* Це застосовується і до груп зі списку дозволених, і до відкритого режиму груп.
* Цитування повідомлення бота рахується як неявна згадка для активації в групі.
* Авторизовані керівні команди (наприклад, `/new`) можуть обходити обмеження згадки.
* Коли групове повідомлення пропускається через вимогу згадки, OpenClaw зберігає його як очікувану історію групи та включає в наступне оброблене групове повідомлення.
* Ліміт історії групи за замовчуванням дорівнює `messages.groupChat.historyLimit` (резервне значення `50`). Можна перевизначити для кожного облікового запису через `channels.zalouser.historyLimit`.
Приклад:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"*": { allow: true, requireMention: true },
"Work Chat": { allow: true, requireMention: false },
},
},
},
}
```
## Кілька облікових записів
Облікові записи зіставляються з профілями `zalouser` у стані OpenClaw. Приклад:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
zalouser: {
enabled: true,
defaultAccount: "default",
accounts: {
work: { enabled: true, profile: "work" },
},
},
},
}
```
## Змінні середовища
Plugin Zalo Personal також може читати вибір профілю зі змінних середовища:
* `ZALOUSER_PROFILE`: ім’я профілю для використання, коли `profile` не задано в конфігурації каналу або облікового запису.
* `ZCA_PROFILE`: застаріле резервне ім’я профілю, використовується лише коли `ZALOUSER_PROFILE` не задано.
Імена профілів вибирають збережені облікові дані входу Zalo у стані OpenClaw. Порядок розв’язання:
1. Явний `profile` у конфігурації.
2. `ZALOUSER_PROFILE`.
3. `ZCA_PROFILE`.
4. Ідентифікатор облікового запису для облікових записів не за замовчуванням або `default` для облікового запису за замовчуванням.
Для налаштувань із кількома обліковими записами краще задавати `profile` для кожного облікового запису в конфігурації, щоб
одна змінна середовища не змушувала кілька облікових записів спільно використовувати один сеанс входу.
## Набір тексту, реакції та підтвердження доставки
* OpenClaw надсилає подію набору тексту перед відправленням відповіді (за можливості).
* Дія реакції на повідомлення `react` підтримується для `zalouser` у діях каналу.
* Використовуйте `remove: true`, щоб прибрати певний emoji реакції з повідомлення.
* Семантика реакцій: [Реакції](/uk/tools/reactions)
* Для вхідних повідомлень, які містять метадані події, OpenClaw надсилає підтвердження доставлено + побачено (за можливості).
## Усунення несправностей
**Вхід не зберігається:**
* `openclaw channels status --probe`
* Повторний вхід: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`
**Ім’я у списку дозволених/назва групи не розв’язалися:**
* Використовуйте числові ідентифікатори в `allowFrom`/`groupAllowFrom` і стабільні ідентифікатори груп у `groups`. Якщо вам навмисно потрібні точні імена друзів/груп, увімкніть `channels.zalouser.dangerouslyAllowNameMatching: true`.
**Оновлено зі старого налаштування на основі CLI:**
* Приберіть будь-які старі припущення про зовнішній процес `zca`.
* Тепер канал повністю працює в OpenClaw без зовнішніх CLI-бінарників.
## Пов’язане
* [Огляд каналів](/uk/channels) — усі підтримувані канали
* [Сполучення](/uk/channels/pairing) — автентифікація DM і процес сполучення
* [Групи](/uk/channels/groups) — поведінка групового чату та обмеження згадок
* [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сеансів для повідомлень
* [Безпека](/uk/gateway/security) — модель доступу та посилення безпеки