---
read_when:
    - Налаштування Zalo Personal для OpenClaw
    - Налагодження входу або потоку повідомлень Zalo Personal
summary: Підтримка особистого облікового запису Zalo через нативний zca-js (вхід за QR-кодом), можливості та конфігурація
title: Zalo personal
x-i18n:
    generated_at: "2026-06-27T17:14:40Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: fdd331d118bfc0d9aba90ac5e42c2ba52e010eafba1342bd3523c64642057dc6
    source_path: channels/zalouser.md
    workflow: 16
---

Статус: експериментально. Ця інтеграція автоматизує **особистий обліковий запис Zalo** через нативний `zca-js` усередині OpenClaw.

<Warning>
Це неофіційна інтеграція, яка може призвести до призупинення або блокування облікового запису. Використовуйте на власний ризик.
</Warning>

## Вбудований 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
{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}
```

4. Перезапустіть Gateway (або завершіть налаштування).
5. Доступ до DM за замовчуванням використовує сполучення; підтвердьте код сполучення під час першого контакту.

## Що це таке

- Повністю працює в процесі через `zca-js`.
- Використовує нативні слухачі подій для отримання вхідних повідомлень.
- Надсилає відповіді напряму через JS API (текст/медіа/посилання).
- Призначено для сценаріїв використання "особистого облікового запису", де Zalo Bot API недоступний.

## Найменування

Ідентифікатор каналу — `zalouser`, щоб явно показати, що це автоматизує **особистий обліковий запис користувача Zalo** (неофіційно). Ми залишаємо `zalo` зарезервованим для потенційної майбутньої офіційної інтеграції Zalo API.

## Пошук ідентифікаторів (каталог)

Використовуйте CLI каталогу, щоб знаходити співрозмовників/групи та їхні ідентифікатори:

```bash
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:<name>`). Під час інтерактивного налаштування введені імена можна перетворити на ідентифікатори за допомогою внутрішньопроцесного пошуку контактів Plugin.

Якщо сире ім’я залишається в конфігурації, під час запуску воно перетворюється лише коли ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`. Без цієї явної згоди перевірки відправника під час виконання працюють лише за ідентифікаторами, а сирі імена ігноруються для авторизації.

Підтвердьте через:

- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser <code>`

## Доступ до груп (необов’язково)

- За замовчуванням: `channels.zalouser.groupPolicy = "open"` (групи дозволені). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, коли воно не задане.
- Обмежити списком дозволених:
  - `channels.zalouser.groupPolicy = "allowlist"`
  - `channels.zalouser.groups` (ключами мають бути стабільні ідентифікатори груп; імена перетворюються на ідентифікатори під час запуску лише коли ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`)
  - `channels.zalouser.groupAllowFrom` (керує тим, які відправники в дозволених групах можуть запускати бота; на статичні групи доступу відправників можна посилатися через `accessGroup:<name>`)
- Заблокувати всі групи: `channels.zalouser.groupPolicy = "disabled"`.
- Майстер налаштування може запитувати списки дозволених груп.
- Під час запуску OpenClaw перетворює імена груп/користувачів у списках дозволених на ідентифікатори та журналює зіставлення лише коли ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`.
- Зіставлення списку дозволених груп за замовчуванням працює лише за ідентифікаторами. Нерозпізнані імена ігноруються для авторизації, якщо не ввімкнено `channels.zalouser.dangerouslyAllowNameMatching: true`.
- `channels.zalouser.dangerouslyAllowNameMatching: true` — це аварійний режим сумісності, який повторно вмикає змінне перетворення імен під час запуску та зіставлення назв груп під час виконання.
- Якщо `groupAllowFrom` не задано, під час виконання перевірки відправників у групах використовують `allowFrom` як резервний варіант.
- Перевірки відправників застосовуються як до звичайних групових повідомлень, так і до керівних команд (наприклад, `/new`, `/reset`).

Приклад:

```json5
{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { allow: true },
        "Work Chat": { allow: true },
      },
    },
  },
}
```

### Обмеження групових згадок

- `channels.zalouser.groups.<group>.requireMention` керує тим, чи потребують групові відповіді згадки.
- Порядок розв’язання: точний id/назва групи -> нормалізований slug групи -> `*` -> типове значення (`true`).
- Це застосовується і до груп зі списку дозволених, і до відкритого режиму груп.
- Цитування повідомлення бота рахується як неявна згадка для активації в групі.
- Авторизовані керівні команди (наприклад, `/new`) можуть обходити обмеження згадки.
- Коли групове повідомлення пропускається через вимогу згадки, OpenClaw зберігає його як очікувану історію групи та включає в наступне оброблене групове повідомлення.
- Ліміт історії групи за замовчуванням дорівнює `messages.groupChat.historyLimit` (резервне значення `50`). Можна перевизначити для кожного облікового запису через `channels.zalouser.historyLimit`.

Приклад:

```json5
{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { allow: true, requireMention: true },
        "Work Chat": { allow: true, requireMention: false },
      },
    },
  },
}
```

## Кілька облікових записів

Облікові записи зіставляються з профілями `zalouser` у стані OpenClaw. Приклад:

```json5
{
  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) — модель доступу та посилення безпеки