Личный Zalo

​

Установка

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 недоступен.

​

Именование

​

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

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

​

Ограничения

• Исходящий текст разбивается на фрагменты по 2000 символов (ограничение клиента Zalo).
• Потоковая передача не поддерживается.

​

Управление доступом (личные сообщения)

• 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 },
      },
    },
  },
}

​

Несколько учётных записей

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

​

Переменные окружения

1. Явно заданный profile в конфигурации.
2. ZALOUSER_PROFILE.
3. ZCA_PROFILE.
4. Идентификатор учётной записи для учётных записей не по умолчанию либо default для учётной записи по умолчанию.

​

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

• OpenClaw отправляет событие набора текста перед отправкой ответа (по возможности).
• Для zalouser в действиях канала поддерживается действие реакции на сообщение react.
  • Используйте 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; теперь канал полностью выполняется внутри процесса с помощью zca-js, без внешнего исполняемого файла CLI.

​

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

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