Личный Zalo

Status: экспериментально. Эта интеграция автоматизирует личный аккаунт 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

Внешний CLI-бинарник zca/openzca не требуется.

Быстрая настройка (для начинающих)

1. Убедитесь, что plugin Zalo Personal доступен.
   • Текущие пакетные релизы OpenClaw уже включают его.
   • Более старые/пользовательские установки могут добавить его вручную командами выше.
2. Войдите (QR, на машине Gateway):
   • openclaw channels login --channel zalouser
   • Отсканируйте QR-код мобильным приложением Zalo.
3. Включите канал:

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

4. Перезапустите Gateway (или завершите настройку).
5. Доступ к личным сообщениям по умолчанию использует сопряжение; подтвердите код сопряжения при первом контакте.

Что это такое

• Полностью выполняется внутри процесса через zca-js.
• Использует нативные слушатели событий для получения входящих сообщений.
• Отправляет ответы напрямую через JS API (текст/медиа/ссылка).
• Предназначено для сценариев с "личным аккаунтом", где Zalo Bot API недоступен.

Именование

ID канала: zalouser, чтобы явно указать, что это автоматизирует личный аккаунт пользователя Zalo (неофициально). Мы сохраняем zalo зарезервированным для потенциальной будущей официальной интеграции с Zalo API.

Поиск ID (каталог)

Используйте CLI каталога, чтобы находить собеседников/группы и их ID:

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 должен использовать стабильные ID пользователей Zalo. Он также может ссылаться на статические группы доступа отправителей (accessGroup:<name>). Во время интерактивной настройки введенные имена можно разрешить в ID с помощью внутрипроцессного поиска контактов plugin.

Если необработанное имя остается в конфигурации, при запуске оно разрешается только когда включено channels.zalouser.dangerouslyAllowNameMatching: true. Без этого явного включения проверки отправителей во время выполнения выполняются только по 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.dangerouslyAllowNameMatching: true)
  • channels.zalouser.groupAllowFrom (управляет тем, какие отправители в разрешенных группах могут запускать бота; на статические группы доступа отправителей можно ссылаться через accessGroup:<name>)
• Заблокировать все группы: channels.zalouser.groupPolicy = "disabled".
• Мастер настройки может запросить списки разрешенных групп.
• При запуске OpenClaw разрешает имена групп/пользователей в списках разрешенных в ID и логирует сопоставление только когда включено channels.zalouser.dangerouslyAllowNameMatching: true.
• Сопоставление списка разрешенных групп по умолчанию выполняется только по ID. Неразрешенные имена игнорируются для авторизации, если не включено channels.zalouser.dangerouslyAllowNameMatching: true.
• channels.zalouser.dangerouslyAllowNameMatching: true — это аварийный режим совместимости, который снова включает изменяемое разрешение имен при запуске и сопоставление имен групп во время выполнения.
• Если groupAllowFrom не задан, во время выполнения используется allowFrom для проверок отправителей в группах.
• Проверки отправителей применяются как к обычным групповым сообщениям, так и к управляющим командам (например, /new, /reset).

Пример:

{  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.

Пример:

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

Несколько аккаунтов

Аккаунты сопоставляются с профилями zalouser в состоянии OpenClaw. Пример:

{  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. ID аккаунта для нестандартных аккаунтов или default для аккаунта по умолчанию.

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

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

• OpenClaw отправляет событие набора текста перед отправкой ответа (по возможности).
• Действие реакции на сообщение react поддерживается для zalouser в действиях канала.
  • Используйте remove: true, чтобы удалить конкретный эмодзи реакции из сообщения.
  • Семантика реакций: Реакции
• Для входящих сообщений, которые включают метаданные событий, OpenClaw отправляет подтверждения доставлено + просмотрено (по возможности).

Устранение неполадок

Вход не сохраняется:

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

Имя из списка разрешенных/группы не разрешилось:

• Используйте числовые ID в allowFrom/groupAllowFrom и стабильные ID групп в groups. Если вам намеренно нужны точные имена друзей/групп, включите channels.zalouser.dangerouslyAllowNameMatching: true.

Обновление со старой настройки на основе CLI:

• Удалите любые старые предположения о внешнем процессе zca.
• Теперь канал полностью работает внутри OpenClaw без внешних CLI-бинарников.

Связанные материалы

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