---
read_when:
    - Налаштування Zalo Personal для OpenClaw
    - Налагодження входу або потоку повідомлень Zalo Personal
summary: Підтримка особистого акаунта Zalo через нативний zca-js (вхід за QR), можливості та конфігурація
title: Zalo Personal
x-i18n:
    generated_at: "2026-04-07T06:53:01Z"
    model: gpt-5.4
    provider: openai
    source_hash: 08f50edb2f4c6fe24972efe5e321f5fd0572c7d29af5c1db808151c7c943dc66
    source_path: channels/zalouser.md
    workflow: 15
---

# Zalo Personal (неофіційно)

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

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

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

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

Якщо ви використовуєте старішу збірку або власне встановлення без Zalo Personal,
встановіть його вручну:

- Встановлення через CLI: `openclaw plugins install @openclaw/zalouser`
- Або з вихідного дерева: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Докладніше: [Плагіни](/uk/tools/plugin)

Зовнішній бінарний файл CLI `zca`/`openzca` не потрібен.

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

1. Переконайтеся, що плагін 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 за замовчуванням використовує pairing; підтвердьте код pairing під час першого контакту.

## Що це таке

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

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

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

## Пошук ID (каталог)

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

```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` приймає ID користувачів або імена. Під час налаштування імена перетворюються на ID за допомогою внутрішньопроцесного пошуку контактів плагіна.

Підтвердження через:

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

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

- Типово: `channels.zalouser.groupPolicy = "open"` (групи дозволені). Використовуйте `channels.defaults.groupPolicy`, щоб перевизначити типове значення, коли його не задано.
- Обмеження через список дозволених:
  - `channels.zalouser.groupPolicy = "allowlist"`
  - `channels.zalouser.groups` (ключами мають бути стабільні ID груп; імена за можливості перетворюються на ID під час запуску)
  - `channels.zalouser.groupAllowFrom` (керує тим, які відправники в дозволених групах можуть активувати бота)
- Заборонити всі групи: `channels.zalouser.groupPolicy = "disabled"`.
- Майстер налаштування може пропонувати списки дозволених груп.
- Під час запуску OpenClaw перетворює імена груп/користувачів у списках дозволених на ID і записує це зіставлення в журнал.
- За замовчуванням зіставлення списку дозволених груп виконується лише за ID. Імена, які не вдалося перетворити, ігноруються для автентифікації, якщо не ввімкнено `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" },
      },
    },
  },
}
```

## Набір тексту, реакції та підтвердження доставки

- OpenClaw надсилає подію набору тексту перед відправленням відповіді (за наявності можливості).
- Дія реакції на повідомлення `react` підтримується для `zalouser` у діях каналу.
  - Використовуйте `remove: true`, щоб видалити конкретний емодзі реакції з повідомлення.
  - Семантика реакцій: [Реакції](/uk/tools/reactions)
- Для вхідних повідомлень, які містять метадані події, OpenClaw надсилає підтвердження delivered + seen (за наявності можливості).

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

**Вхід не зберігається:**

- `openclaw channels status --probe`
- Увійдіть повторно: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`

**Назва в списку дозволених/групи не перетворилася:**

- Використовуйте числові ID в `allowFrom`/`groupAllowFrom`/`groups` або точні імена друзів/груп.

**Оновилися зі старого налаштування на основі CLI:**

- Приберіть будь-які старі припущення про зовнішній процес `zca`.
- Тепер канал повністю працює в OpenClaw без зовнішніх бінарних файлів CLI.

## Пов’язане

- [Огляд каналів](/uk/channels) — усі підтримувані канали
- [Pairing](/uk/channels/pairing) — автентифікація DM і процес pairing
- [Групи](/uk/channels/groups) — поведінка групового чату та вимога згадки
- [Маршрутизація каналів](/uk/channels/channel-routing) — маршрутизація сесій для повідомлень
- [Безпека](/uk/gateway/security) — модель доступу та зміцнення захисту
