> ## 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

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

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

## Установка

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw plugins install @openclaw/zalouser
```

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

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

1. Установите плагин (см. выше).
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` (без внешнего исполняемого файла `zca`/`openzca`).
* Использует нативные обработчики событий (`message`, `error`) для получения входящих сообщений.
* Отправляет ответы напрямую через JS API (текст, медиафайлы и ссылки).
* Предназначена для сценариев с «личной учётной записью», в которых Zalo Bot API недоступен.

## Именование

Идентификатор канала — `zalouser`, чтобы явно указать, что интеграция автоматизирует **личную учётную запись пользователя Zalo** (неофициально). `zalo` зарезервирован для возможной будущей официальной интеграции с API Zalo.

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

```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` следует использовать стабильные идентификаторы пользователей 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`.

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

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

Пример:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { enabled: true, requireMention: true },
        "Work Chat": { enabled: 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" },
      },
    },
  },
}
```

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

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

| Переменная | Назначение |
| - | - |
| `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`, чтобы удалить из сообщения определённую реакцию-эмодзи.
  * Семантика реакций: [Реакции](https://docs2.openclaw.ai/ru/tools/reactions.md)
* Для входящих сообщений, содержащих метаданные события, 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.

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

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