> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Личный Zalo
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
channels: {
zalouser: {
groupPolicy: "allowlist",
groups: {
"*": { allow: true, requireMention: true },
"Work Chat": { allow: true, requireMention: false },
},
},
},
}
```
## Несколько аккаунтов
Аккаунты сопоставляются с профилями `zalouser` в состоянии OpenClaw. Пример:
```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
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) — модель доступа и усиление защиты