---
read_when:
    - Настройка Zalo Personal для OpenClaw
    - Отладка входа в Zalo Personal и обмена сообщениями
summary: Поддержка личной учётной записи Zalo через нативную библиотеку zca-js (вход по QR-коду), возможности и настройка
title: Личный Zalo
x-i18n:
    generated_at: "2026-07-13T19:34:39Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: 962697c4a56dfb733fe4973e23129ccb365506e35c09e673365842f45a837949
    source_path: channels/zalouser.md
    workflow: 16
---

Статус: экспериментальная функция. Эта интеграция автоматизирует **личную учётную запись Zalo** через нативную библиотеку `zca-js`, выполняемую внутри процесса, без внешнего исполняемого файла CLI.

<Warning>
Это неофициальная интеграция, которая может привести к приостановке или блокировке учётной записи. Используйте её на свой страх и риск.
</Warning>

## Установка

Zalo Personal — официальный внешний плагин, не входящий в состав ядра. Установите его перед использованием:

```bash
openclaw plugins install @openclaw/zalouser
```

- Закрепить версию: `openclaw plugins install @openclaw/zalouser@<version>`
- Из исходного кода: `openclaw plugins install ./path/to/local/zalouser-plugin`
- Подробнее: [Плагины](/ru/tools/plugin)

## Быстрая настройка

1. Установите плагин (см. выше).
2. Войдите в систему (по QR-коду на компьютере с Gateway):
   - `openclaw channels login --channel zalouser`
   - Отсканируйте QR-код в мобильном приложении Zalo.
3. Включите канал:

```json5
{
  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.

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

```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` следует использовать стабильные идентификаторы пользователей 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` как запасной вариант.

Пример:

```json5
{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { enabled: true },
        "Work Chat": { enabled: true },
      },
    },
  },
}
```

<Note>
`channels.zalouser.groups.<id>.allow` — устаревшее имя поля; в текущей конфигурации используется `enabled`. `openclaw doctor --fix` автоматически переносит `allow` в `enabled`.
</Note>

### Активация по упоминанию в группах

- `channels.zalouser.groups.<group>.requireMention` определяет, требуется ли упоминание для ответов в группе.
- Порядок разрешения: идентификатор группы -> псевдоним `group:<id>` -> имя/слаг группы (кандидаты на основе имени применяются только при `dangerouslyAllowNameMatching: true`) -> `*` -> значение по умолчанию (`true`).
- Применяется как к группам из списка разрешений, так и к режиму открытых групп.
- Цитирование сообщения бота считается неявным упоминанием для активации в группе.
- Авторизованные управляющие команды (например, `/new`) могут обходить требование упоминания.
- Если групповое сообщение пропущено из-за требования упоминания, OpenClaw сохраняет его в ожидающей истории группы и добавляет к следующему обработанному групповому сообщению.
- Ограничение истории группы: `channels.zalouser.historyLimit`, затем `messages.groupChat.historyLimit`, затем запасное значение `50`.

Пример:

```json5
{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { enabled: true, requireMention: true },
        "Work Chat": { enabled: true, requireMention: false },
      },
    },
  },
}
```

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

Учётные записи сопоставляются с профилями `zalouser` в состоянии OpenClaw. Пример:

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

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

Профиль также можно выбрать с помощью переменных окружения:

| Переменная         | Назначение                                                                    |
| ------------------ | -------------------------------------------------------------------------- |
| `ZALOUSER_PROFILE` | Имя профиля, используемое, если `profile` не задан в конфигурации канала или учётной записи. |
| `ZCA_PROFILE`      | Устаревший запасной вариант, используемый только тогда, когда `ZALOUSER_PROFILE` не задан.             |

Имена профилей выбирают сохранённые учётные данные для входа в Zalo из состояния OpenClaw. Порядок разрешения:

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

При настройке нескольких учётных записей рекомендуется задавать `profile` для каждой учётной записи в конфигурации, чтобы одна переменная окружения не приводила к совместному использованию одного сеанса входа несколькими учётными записями.

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

- OpenClaw отправляет событие набора текста перед отправкой ответа (по возможности).
- Для `zalouser` в действиях канала поддерживается действие реакции на сообщение `react`.
  - Используйте `remove: true`, чтобы удалить из сообщения определённую реакцию-эмодзи.
  - Семантика реакций: [Реакции](/ru/tools/reactions)
- Для входящих сообщений, содержащих метаданные события, 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.

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

- [Обзор каналов](/ru/channels) — все поддерживаемые каналы
- [Сопряжение](/ru/channels/pairing) — аутентификация в личных сообщениях и процесс сопряжения
- [Группы](/ru/channels/groups) — поведение групповых чатов и активация по упоминанию
- [Маршрутизация каналов](/ru/channels/channel-routing) — маршрутизация сеансов для сообщений
- [Безопасность](/ru/gateway/security) — модель доступа и усиление защиты