---
read_when:
- Настройка Zalo Personal для OpenClaw
- Отладка входа в Zalo Personal или потока сообщений
summary: Поддержка личной учетной записи Zalo через нативный zca-js (вход по QR-коду), возможности и конфигурация
title: Личный Zalo
x-i18n:
generated_at: "2026-06-28T22:38:43Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: fdd331d118bfc0d9aba90ac5e42c2ba52e010eafba1342bd3523c64642057dc6
source_path: channels/zalouser.md
workflow: 16
---
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](/ru/tools/plugin)
Внешний CLI-бинарник `zca`/`openzca` не требуется.
## Быстрая настройка (для начинающих)
1. Убедитесь, что plugin Zalo Personal доступен.
- Текущие пакетные релизы OpenClaw уже включают его.
- Более старые/пользовательские установки могут добавить его вручную командами выше.
2. Войдите (QR, на машине Gateway):
- `openclaw channels login --channel zalouser`
- Отсканируйте QR-код мобильным приложением Zalo.
3. Включите канал:
```json5
{
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:
```bash
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:`). Во время интерактивной настройки введенные имена можно разрешить в ID с помощью внутрипроцессного поиска контактов plugin.
Если необработанное имя остается в конфигурации, при запуске оно разрешается только когда включено `channels.zalouser.dangerouslyAllowNameMatching: true`. Без этого явного включения проверки отправителей во время выполнения выполняются только по ID, а необработанные имена игнорируются для авторизации.
Подтвердите через:
- `openclaw pairing list zalouser`
- `openclaw pairing approve zalouser `
## Доступ к группам (необязательно)
- По умолчанию: `channels.zalouser.groupPolicy = "open"` (группы разрешены). Используйте `channels.defaults.groupPolicy`, чтобы переопределить значение по умолчанию, когда оно не задано.
- Ограничьте списком разрешенных:
- `channels.zalouser.groupPolicy = "allowlist"`
- `channels.zalouser.groups` (ключами должны быть стабильные ID групп; имена разрешаются в ID при запуске только когда включено `channels.zalouser.dangerouslyAllowNameMatching: true`)
- `channels.zalouser.groupAllowFrom` (управляет тем, какие отправители в разрешенных группах могут запускать бота; на статические группы доступа отправителей можно ссылаться через `accessGroup:`)
- Заблокировать все группы: `channels.zalouser.groupPolicy = "disabled"`.
- Мастер настройки может запросить списки разрешенных групп.
- При запуске OpenClaw разрешает имена групп/пользователей в списках разрешенных в ID и логирует сопоставление только когда включено `channels.zalouser.dangerouslyAllowNameMatching: true`.
- Сопоставление списка разрешенных групп по умолчанию выполняется только по ID. Неразрешенные имена игнорируются для авторизации, если не включено `channels.zalouser.dangerouslyAllowNameMatching: true`.
- `channels.zalouser.dangerouslyAllowNameMatching: true` — это аварийный режим совместимости, который снова включает изменяемое разрешение имен при запуске и сопоставление имен групп во время выполнения.
- Если `groupAllowFrom` не задан, во время выполнения используется `allowFrom` для проверок отправителей в группах.
- Проверки отправителей применяются как к обычным групповым сообщениям, так и к управляющим командам (например, `/new`, `/reset`).
Пример:
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groupAllowFrom: ["1471383327500481391"],
groups: {
"123456789": { allow: true },
"Work Chat": { allow: true },
},
},
},
}
```
### Фильтрация упоминаний в группах
- `channels.zalouser.groups..requireMention` управляет тем, требуют ли ответы в группе упоминания.
- Порядок разрешения: точный id/имя группы -> нормализованный slug группы -> `*` -> значение по умолчанию (`true`).
- Это применяется как к группам из списка разрешенных, так и к открытому режиму групп.
- Цитирование сообщения бота считается неявным упоминанием для активации в группе.
- Авторизованные управляющие команды (например, `/new`) могут обходить фильтрацию упоминаний.
- Когда групповое сообщение пропускается из-за требования упоминания, OpenClaw сохраняет его как ожидающую групповую историю и включает в следующее обработанное групповое сообщение.
- Лимит истории группы по умолчанию берется из `messages.groupChat.historyLimit` (резервное значение `50`). Его можно переопределить для каждого аккаунта через `channels.zalouser.historyLimit`.
Пример:
```json5
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"*": { allow: true, requireMention: true },
"Work Chat": { allow: true, requireMention: false },
},
},
},
}
```
## Несколько аккаунтов
Аккаунты сопоставляются с профилями `zalouser` в состоянии OpenClaw. Пример:
```json5
{
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`, чтобы удалить конкретный эмодзи реакции из сообщения.
- Семантика реакций: [Реакции](/ru/tools/reactions)
- Для входящих сообщений, которые включают метаданные событий, 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-бинарников.
## Связанные материалы
- [Обзор каналов](/ru/channels) — все поддерживаемые каналы
- [Сопряжение](/ru/channels/pairing) — аутентификация личных сообщений и процесс сопряжения
- [Группы](/ru/channels/groups) — поведение группового чата и фильтрация упоминаний
- [Маршрутизация каналов](/ru/channels/channel-routing) — маршрутизация сессий для сообщений
- [Безопасность](/ru/gateway/security) — модель доступа и усиление защиты