Особистий Zalo

Статус: експериментальна функція. Ця інтеграція автоматизує особистий обліковий запис Zalo за допомогою вбудованої бібліотеки zca-js, що працює в межах процесу, без зовнішнього виконуваного файла CLI.

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

Встановлення

Zalo Personal — це офіційний зовнішній плагін, який не входить до складу ядра. Установіть його перед використанням:

openclaw plugins install @openclaw/zalouser

Зафіксувати версію: openclaw plugins install @openclaw/zalouser@<version>
З локальної копії вихідного коду: openclaw plugins install ./path/to/local/zalouser-plugin
Докладніше: Плагіни

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

Установіть плагін (див. вище).
Увійдіть (за QR-кодом на машині з Gateway):
- openclaw channels login --channel zalouser
- Відскануйте QR-код у мобільному застосунку Zalo.
Увімкніть канал:

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

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

Що це таке

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

Іменування

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

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

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

Обмеження

Вихідний текст розбивається на частини по 2000 символів (обмеження клієнта Zalo).
Потокове передавання не підтримується.

Керування доступом (приватні повідомлення)

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled (типове значення: pairing). У channels.zalouser.allowFrom слід використовувати стабільні ідентифікатори користувачів Zalo. Також можна посилатися на статичні групи доступу відправників (accessGroup:<name>). Під час інтерактивного налаштування введені імена можна зіставити з ідентифікаторами за допомогою вбудованого в процес пошуку контактів плагіна. Якщо в конфігурації залишається необроблене ім’я, під час запуску воно зіставляється лише тоді, коли ввімкнено channels.zalouser.dangerouslyAllowNameMatching: true. Без цієї явної згоди перевірки відправників під час виконання здійснюються лише за ідентифікаторами, а необроблені імена не враховуються під час авторизації. Схвалення:

openclaw pairing list zalouser
openclaw pairing approve zalouser <code>

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

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

Приклад:

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

channels.zalouser.groups.<id>.allow — застаріла назва поля; поточна конфігурація використовує enabled. Команда openclaw doctor --fix автоматично переносить allow до enabled.

Перевірка згадок у групах

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

Приклад:

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

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

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

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

Змінні середовища

Профіль також можна вибрати за допомогою змінних середовища:

Змінна	Призначення
`ZALOUSER_PROFILE`	Назва профілю, яку слід використовувати, якщо `profile` не задано в конфігурації каналу або облікового запису.
`ZCA_PROFILE`	Застарілий резервний варіант, який використовується лише тоді, коли `ZALOUSER_PROFILE` не задано.

Назви профілів визначають збережені облікові дані для входу в Zalo у стані OpenClaw. Порядок визначення:

Явно заданий profile у конфігурації.
ZALOUSER_PROFILE.
ZCA_PROFILE.
Ідентифікатор облікового запису для облікових записів, відмінних від типового, або default для типового облікового запису.

Для налаштувань із кількома обліковими записами рекомендовано задавати profile для кожного облікового запису в конфігурації, щоб одна змінна середовища не змушувала кілька облікових записів використовувати спільний сеанс входу.

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

OpenClaw надсилає подію набору тексту перед відправленням відповіді (за можливості).
Дія реакції на повідомлення react підтримується для zalouser у діях каналу.
- Використовуйте remove: true, щоб видалити певну реакцію-емодзі з повідомлення.
- Семантика реакцій: Реакції
Для вхідних повідомлень, що містять метадані події, OpenClaw надсилає підтвердження доставки та перегляду (за можливості).

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

Сеанс входу не зберігається:

openclaw channels status --probe
Повторний вхід: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

Не вдалося зіставити ім’я зі списку дозволених або назву групи:

Використовуйте числові ідентифікатори в allowFrom/groupAllowFrom і стабільні ідентифікатори груп у groups. Якщо вам навмисно потрібно використовувати точні імена друзів або груп, увімкніть channels.zalouser.dangerouslyAllowNameMatching: true.

Оновлення зі старого зовнішнього налаштування на основі zca/CLI:

Усуньте всі припущення щодо зовнішнього процесу zca; тепер канал повністю працює в межах процесу через zca-js, без зовнішнього виконуваного файла CLI.

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

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

Overview

Mainstream messaging

Developer and self-hosted

Regional platforms

Configuration

Особистий Zalo

Встановлення

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

Що це таке

Іменування

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

Обмеження

Керування доступом (приватні повідомлення)

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

Перевірка згадок у групах

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

Змінні середовища

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

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

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

​Встановлення

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

​Що це таке

​Іменування

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

​Обмеження

​Керування доступом (приватні повідомлення)

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

​Перевірка згадок у групах

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

​Змінні середовища

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

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

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

Встановлення

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

Що це таке

Іменування

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

Обмеження

Керування доступом (приватні повідомлення)

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

Перевірка згадок у групах

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

Змінні середовища

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

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

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