Zalo Personal (неофициальный)

Статус: экспериментальный. Эта интеграция автоматизирует личный аккаунт Zalo через нативный zca-js внутри OpenClaw.

Предупреждение: Это неофициальная интеграция, которая может привести к приостановке/блокировке аккаунта. Используйте на свой страх и риск.

Требуется плагин

Zalo Personal поставляется как плагин и не входит в базовую установку.

  • Установка через CLI: openclaw plugins install @openclaw/zalouser
  • Или из исходной копии: openclaw plugins install ./extensions/zalouser
  • Подробнее: Плагины

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

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

  1. Установите плагин (см. выше).
  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 пользователей или имена. При онбординге имена преобразуются в 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 не задан, runtime использует fallback к 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 (fallback 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" },
      },
    },
  },
}

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

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

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

Логин не сохраняется:

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

Имя в списке доступа/группе не преобразовалось:

  • Используйте числовые ID в allowFrom/groupAllowFrom/groups или точные имена друзей/групп.

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

  • Удалите все зависимости от старого внешнего процесса zca.
  • Канал теперь полностью работает внутри OpenClaw без внешних CLI-бинарников.
arrow_back
Назад
Zalo
Далее
Pairing
arrow_forward