Перейти к основному содержанию
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",
    },
  },
}
  1. Перезапустите Gateway (или завершите настройку).
  2. Доступ к личным сообщениям по умолчанию использует сопряжение; подтвердите код сопряжения при первом контакте.

​
Что это такое

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

​
Именование

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

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

Используйте CLI каталога, чтобы находить собеседников/группы и их ID: 
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 должен использовать стабильные 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-бинарников.

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