Личный 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 зарезервирован для возможной будущей официальной интеграции с API Zalo.

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

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 отправляет событие набора текста перед отправкой ответа (по возможности).
• Для 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/CLI:

• Удалите все предположения о внешнем процессе zca; теперь канал полностью выполняется внутри процесса с помощью zca-js, без внешнего исполняемого файла CLI.

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

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