Особистий 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
• Докладніше: Плагіни

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

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

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

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

Що це таке

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

Іменування

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

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

openclaw directory self --channel zalouseropenclaw 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.<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" },      },    },  },}

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

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

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

1. Явно заданий profile у конфігурації.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. Ідентифікатор облікового запису для облікових записів, відмінних від типового, або 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.

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

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