---
read_when:
    - Настройка Matrix в OpenClaw
    - Настройка сквозного шифрования и верификации в Matrix
summary: Статус поддержки Matrix, настройка и примеры конфигурации
title: Matrix
x-i18n:
    generated_at: "2026-07-16T16:04:22Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: ca704ff911dbe97242d42727561fbce59f27e190343d2343dfad46289c1e0b94
    source_path: channels/matrix.md
    workflow: 16
---

Matrix — загружаемый плагин канала (`@openclaw/matrix`), созданный на основе официального `matrix-js-sdk`. Он поддерживает личные сообщения, комнаты, ветки, медиафайлы, реакции, опросы, геолокацию и сквозное шифрование.

## Установка

```bash
openclaw plugins install @openclaw/matrix
```

Для спецификаций плагинов без квалификатора сначала выполняется поиск в ClawHub, а затем используется резервный вариант с npm. Принудительно укажите источник с помощью `openclaw plugins install clawhub:@openclaw/matrix` или `npm:@openclaw/matrix`. Из локальной рабочей копии: `openclaw plugins install ./path/to/local/matrix-plugin`.

`plugins install` регистрирует и включает плагин; отдельный шаг `enable` не требуется. Канал всё равно не будет работать, пока не будет настроен, как описано ниже. Общие правила установки см. в разделе [Плагины](/ru/tools/plugin).

## Настройка

1. Создайте учётную запись Matrix на своём домашнем сервере.
2. Настройте `channels.matrix` с помощью `homeserver` + `accessToken` или `homeserver` + `userId` + `password`.
3. Перезапустите Gateway.
4. Начните переписку с ботом в личных сообщениях или пригласите его в комнату. Новые приглашения принимаются, только если это разрешено параметром [`autoJoin`](#auto-join).

### Интерактивная настройка

```bash
openclaw channels add
openclaw configure --section channels
```

Мастер запрашивает URL домашнего сервера, метод аутентификации (токен или пароль), идентификатор пользователя (только при аутентификации по паролю), необязательное имя устройства, необходимость включения сквозного шифрования, а также параметры доступа к комнатам и автоматического присоединения. Если соответствующие переменные среды `MATRIX_*` уже существуют, а для учётной записи не сохранены данные аутентификации, мастер предлагает использовать переменные среды. Перед сохранением списка разрешённых значений разрешите имена комнат с помощью `openclaw channels resolve --channel matrix "Project Room"`. При включении сквозного шифрования мастер выполняет ту же начальную настройку, что и [`openclaw matrix encryption setup`](#encryption-and-verification).

### Минимальная конфигурация

На основе токена:

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      dm: { policy: "pairing" },
    },
  },
}
```

На основе пароля (токен кэшируется после первого входа):

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      userId: "@bot:example.org",
      password: "replace-me", // pragma: allowlist secret
      deviceName: "OpenClaw Gateway",
    },
  },
}
```

### Автоматическое присоединение

Значение `channels.matrix.autoJoin` по умолчанию — `"off"`: бот не появится в новых комнатах или личных переписках по новым приглашениям, пока вы не присоединитесь вручную. В момент приглашения OpenClaw не может определить, является ли оно приглашением в личную переписку или группу, поэтому каждое приглашение сначала обрабатывается параметром `autoJoin`; параметр `dm.policy` применяется только позднее, после присоединения бота и определения типа комнаты.

<Warning>
Укажите `autoJoin: "allowlist"` вместе с `autoJoinAllowlist`, чтобы ограничить принимаемые приглашения, или `autoJoin: "always"`, чтобы принимать все приглашения.

`autoJoinAllowlist` принимает только `!roomId:server`, `#alias:server` или `*`. Простые имена комнат отклоняются; псевдонимы разрешаются через домашний сервер, а не на основании состояния, заявленного комнатой, из которой поступило приглашение.
</Warning>

```json5
{
  channels: {
    matrix: {
      autoJoin: "allowlist",
      autoJoinAllowlist: ["!ops:example.org", "#support:example.org"],
      groups: {
        "!ops:example.org": { requireMention: true },
      },
    },
  },
}
```

### Форматы целей списка разрешённых значений

- Личные сообщения (`dm.allowFrom`, `groupAllowFrom`, `groups.<room>.users`): используйте `@user:server`. По умолчанию отображаемые имена игнорируются, поскольку они изменяемы; задавайте `dangerouslyAllowNameMatching: true` только для явной совместимости с отображаемыми именами.
- Ключи списка разрешённых комнат (`groups`, устаревший псевдоним `rooms`): используйте `!room:server` или `#alias:server`. Простые имена игнорируются, если не задано `dangerouslyAllowNameMatching: true`.
- Списки разрешённых приглашений (`autoJoinAllowlist`): используйте `!room:server`, `#alias:server` или `*`. Простые имена отклоняются всегда.

### Нормализация идентификатора учётной записи

Мастер преобразует удобочитаемое имя в нормализованный идентификатор учётной записи (`Ops Bot` -> `ops-bot`). В именах переменных среды с областью действия знаки пунктуации экранируются шестнадцатеричными кодами, чтобы исключить коллизии учётных записей: `-` (0x2D) преобразуется в `_X2D_`, поэтому `ops-prod` соответствует префиксу переменных среды `MATRIX_OPS_X2D_PROD_`.

### Кэшированные учётные данные

Matrix кэширует учётные данные в `~/.openclaw/credentials/matrix/`: `credentials.json` для учётной записи по умолчанию и `credentials-<account>.json` для именованных учётных записей. При наличии кэшированных учётных данных OpenClaw считает Matrix настроенным даже без `accessToken` в файле конфигурации — это относится к настройке, `openclaw doctor` и проверкам состояния канала.

### Переменные среды

Переменные среды, соответствующие ключам конфигурации, используются, если эквивалентный ключ конфигурации не задан. Для учётной записи по умолчанию используются имена без префикса; для именованных учётных записей перед суффиксом вставляется токен учётной записи (см. [нормализацию](#account-id-normalization)).

| Учётная запись по умолчанию       | Именованная учётная запись (`<ID>` = токен учётной записи) |
| --------------------- | -------------------------------------- |
| `MATRIX_HOMESERVER`   | `MATRIX_<ID>_HOMESERVER`               |
| `MATRIX_ACCESS_TOKEN` | `MATRIX_<ID>_ACCESS_TOKEN`             |
| `MATRIX_USER_ID`      | `MATRIX_<ID>_USER_ID`                  |
| `MATRIX_PASSWORD`     | `MATRIX_<ID>_PASSWORD`                 |
| `MATRIX_DEVICE_ID`    | `MATRIX_<ID>_DEVICE_ID`                |
| `MATRIX_DEVICE_NAME`  | `MATRIX_<ID>_DEVICE_NAME`              |

Для учётной записи `ops` имена принимают вид `MATRIX_OPS_HOMESERVER`, `MATRIX_OPS_ACCESS_TOKEN` и т. д. `MATRIX_HOMESERVER` (и любой вариант `*_HOMESERVER` с областью действия) нельзя задать из файла `.env` рабочей области; см. раздел [Файлы `.env` рабочей области](/ru/gateway/security).

<Note>
Ключ восстановления не является переменной среды, соответствующей конфигурации: OpenClaw никогда не считывает его непосредственно из среды. В подсказке CLI предлагается передать его через конвейер из переменной оболочки с именем `MATRIX_RECOVERY_KEY` для учётной записи по умолчанию или `MATRIX_RECOVERY_KEY_<ID>` (обычный идентификатор учётной записи в верхнем регистре без шестнадцатеричного экранирования) для именованной учётной записи — см. раздел [Проверка этого устройства с помощью ключа восстановления](#verify-this-device-with-a-recovery-key).
</Note>

## Пример конфигурации

Практичная базовая конфигурация с сопряжением личных сообщений, списком разрешённых комнат и сквозным шифрованием:

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,

      dm: {
        policy: "pairing",
        sessionScope: "per-room",
        threadReplies: "off",
      },

      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },

      autoJoin: "allowlist",
      autoJoinAllowlist: ["!roomid:example.org"],
      threadReplies: "inbound",
      replyToMode: "off",
      streaming: { mode: "partial" },
    },
  },
}
```

## Потоковые предпросмотры

Потоковая передача ответов в Matrix включается явно. `streaming.mode` определяет, как OpenClaw доставляет формируемый ответ ассистента; `streaming.block.enabled` определяет, сохраняется ли каждый завершённый блок как отдельное сообщение Matrix.

```json5
{
  channels: {
    matrix: {
      streaming: { mode: "partial" },
    },
  },
}
```

Чтобы сохранить предпросмотр ответа в реальном времени, но скрыть промежуточные строки инструментов и хода выполнения:

```json5
{
  channels: {
    matrix: {
      streaming: {
        mode: "partial",
        preview: {
          toolProgress: false,
        },
      },
    },
  },
}
```

Полная конфигурация принимает `{ mode, chunkMode, block, preview, progress }`:

```json5
{
  channels: {
    matrix: {
      streaming: {
        mode: "progress",
        progress: {
          label: "auto", // выбрать из настроенных или встроенных меток (false, чтобы скрыть)
          labels: ["Thinking", "Writing", "Searching"], // варианты для label: "auto"
          maxLines: 8, // максимальное число прокручиваемых строк хода выполнения (по умолчанию: 8)
          maxLineChars: 120, // максимальное число символов в строке до усечения (по умолчанию: 120)
          toolProgress: true, // показывать работу инструментов и ход выполнения (по умолчанию: true)
        },
      },
    },
  },
}
```

- `progress.label`: пользовательская метка; `"auto"`/не задано — выбрать настроенную или встроенную метку; `false` — скрыть её.
- `progress.labels`: варианты, используемые только тогда, когда `label` имеет значение `"auto"` или не задано.
- `progress.maxLines`: максимальное число прокручиваемых строк хода выполнения, сохраняемых в черновике; более старые строки сверх этого числа удаляются.
- `progress.maxLineChars`: максимальное число символов в компактной строке хода выполнения до усечения.
- `progress.toolProgress`: при значении `true` (по умолчанию) текущая работа инструментов и ход выполнения отображаются в черновике.

| `streaming.mode`  | Поведение                                                                                                                                                 |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"off"` (по умолчанию) | Дождаться полного ответа и отправить его один раз.                                                                                                                      |
| `"partial"`       | По мере формирования моделью текущего блока редактировать на месте одно обычное текстовое сообщение. Стандартные клиенты могут отправить уведомление при первом предпросмотре, а не после окончательного изменения.          |
| `"quiet"`         | То же, что `"partial"`, но сообщение представляет собой уведомление без оповещения. Получатели получают оповещение, когда индивидуальное правило push-уведомлений соответствует окончательной редакции (см. ниже). |
| `"progress"`      | Отправлять отдельные компактные строки хода выполнения с помощью черновика хода выполнения.                                                                                          |

`streaming.block.enabled` (по умолчанию `false`) не зависит от `streaming.mode`:

| `streaming.mode`        | `block.enabled: true`                                               | `block.enabled: false` (по умолчанию)                     |
| ----------------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
| `"partial"` / `"quiet"` | Активный черновик текущего блока; завершённые блоки сохраняются как сообщения | Активный черновик текущего блока, окончательно обновляемый на месте |
| `"off"`                 | Одно сообщение Matrix с оповещением для каждого завершённого блока                     | Одно сообщение Matrix с оповещением для полного ответа      |

Примечания:

- Если предпросмотр превышает ограничение Matrix на размер одного события, OpenClaw прекращает потоковую передачу предпросмотра и переходит к отправке только окончательного результата.
- В ответах с медиафайлами вложения всегда отправляются обычным способом; если устаревший предпросмотр нельзя безопасно использовать повторно, OpenClaw удаляет его перед отправкой окончательного ответа с медиафайлом.
- При активной потоковой передаче предпросмотра обновления хода выполнения инструментов включены по умолчанию. Задайте `streaming.preview.toolProgress: false`, чтобы сохранить редактирование предпросмотра для текста ответа, но оставить ход выполнения инструментов в обычном канале доставки.
- Редактирование предпросмотра требует дополнительных вызовов API Matrix. Оставьте `streaming.mode: "off"` для наиболее консервативного профиля ограничений частоты запросов.
- Устаревшие скалярные и логические значения `streaming`, а также плоские ключи `blockStreaming` / `chunkMode` преобразуются в эту вложенную структуру командой `openclaw doctor --fix`.

## Голосовые сообщения

Входящие голосовые сообщения Matrix расшифровываются до проверки упоминания в комнате, поэтому голосовое сообщение с именем бота может активировать агента в комнате `requireMention: true`, а агент получает расшифровку вместо одного лишь заполнителя аудиовложения.

Matrix использует общий поставщик обработки аудиофайлов в `tools.media.audio`, например OpenAI `gpt-4o-mini-transcribe`. Настройку поставщика и ограничения см. в разделе [Обзор инструментов для работы с медиафайлами](/ru/tools/media-overview).

- События `m.audio` и события `m.file` с MIME-типом `audio/*` подходят для обработки.
- В зашифрованных комнатах OpenClaw расшифровывает вложение через существующий путь обработки медиафайлов Matrix перед транскрибированием.
- В промпте агента транскрипция помечается как созданная машиной и недоверенная.
- Вложение помечается как уже транскрибированное, чтобы последующие инструменты обработки медиафайлов не транскрибировали его повторно.
- Установите `tools.media.audio.enabled: false`, чтобы глобально отключить транскрибирование аудио.

## Метаданные подтверждений

Нативные запросы подтверждения Matrix представляют собой обычные события `m.room.message` со специфичным для OpenClaw содержимым в ключе `com.openclaw.approval`. Стандартные клиенты по-прежнему отображают текстовое тело; клиенты с поддержкой OpenClaw могут считывать структурированные идентификатор, тип и состояние подтверждения, варианты решения, а также сведения о выполнении и плагине.

Если запрос слишком длинный для одного события Matrix, OpenClaw разбивает видимый текст на части и добавляет `com.openclaw.approval` только к первой части. Реакции разрешения и отклонения привязываются к этому первому событию, поэтому для длинных запросов сохраняется та же цель подтверждения, что и для запросов из одного события.

### Правила push-уведомлений для тихих финализированных предпросмотров при самостоятельном размещении

`streaming.mode: "quiet"` уведомляет получателей только после финализации блока или хода — правило push-уведомлений для каждого пользователя должно соответствовать маркеру финализированного предпросмотра. Полную настройку см. в разделе [Правила push-уведомлений Matrix для тихих предпросмотров](/ru/channels/matrix-push-rules).

## Комнаты для взаимодействия ботов

По умолчанию сообщения Matrix от других настроенных учётных записей OpenClaw Matrix игнорируются. Используйте `allowBots`, чтобы намеренно разрешить обмен данными между агентами:

```json5
{
  channels: {
    matrix: {
      allowBots: "mentions", // true | "mentions"
      groups: {
        "!roomid:example.org": {
          requireMention: true,
        },
      },
    },
  },
}
```

- `allowBots: true` принимает сообщения от других настроенных учётных записей ботов Matrix в разрешённых комнатах и личных сообщениях.
- `allowBots: "mentions"` принимает такие сообщения в комнатах, только если в них явно упоминается этот бот; личные сообщения разрешены в любом случае.
- `groups.<room>.allowBots` переопределяет настройку уровня учётной записи для одной комнаты.
- Принятые сообщения от настроенных ботов используют общую [защиту от циклов ботов](/ru/channels/bot-loop-protection). Настройте `channels.defaults.botLoopProtection`, а затем переопределите значение для отдельной учётной записи с помощью `channels.matrix.botLoopProtection` или для отдельной комнаты с помощью `channels.matrix.groups.<room>.botLoopProtection`.
- OpenClaw по-прежнему игнорирует сообщения от того же идентификатора пользователя Matrix, чтобы избежать циклов ответов самому себе.
- В Matrix нет нативного признака бота; OpenClaw считает сообщение «созданным ботом», если оно отправлено другой настроенной учётной записью Matrix на этом Gateway OpenClaw.

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

## Шифрование и верификация

В зашифрованных комнатах (E2EE) исходящие события с изображениями используют `thumbnail_file`, поэтому предпросмотры изображений шифруются вместе с полным вложением; в незашифрованных комнатах используется обычный `thumbnail_url`. Настройка не требуется — плагин автоматически определяет состояние E2EE.

Все команды `openclaw matrix` поддерживают `--verbose` (полная диагностика), `--json` (машиночитаемый вывод) и `--account <id>` (конфигурации с несколькими учётными записями). По умолчанию вывод краткий.

### Включение шифрования

```bash
openclaw matrix encryption setup
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix encryption setup --recovery-key-stdin
```

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

- `--recovery-key-stdin` считывает ключ восстановления из стандартного ввода, не раскрывая его в аргументах процесса; `--recovery-key <key>` остаётся доступным для совместимости
- `--force-reset-cross-signing` удаляет текущую идентичность перекрёстной подписи и создаёт новую (только для намеренного использования)

Для новой учётной записи включите E2EE при её создании:

```bash
openclaw matrix account add \
  --homeserver https://matrix.example.org \
  --access-token syt_xxx \
  --enable-e2ee
```

`--encryption` — псевдоним для `--enable-e2ee`. Эквивалентная ручная конфигурация:

```json5
{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_xxx",
      encryption: true,
      dm: { policy: "pairing" },
    },
  },
}
```

### Состояние и сигналы доверия

```bash
openclaw matrix verify status
openclaw matrix verify status --include-recovery-key --json
```

`verify status` сообщает о трёх независимых сигналах доверия (`--verbose` показывает их все):

- `Locally trusted`: доверие установлено только этим клиентом
- `Cross-signing verified`: SDK сообщает о верификации посредством перекрёстной подписи
- `Signed by owner`: подписано собственным ключом самоподписи пользователя (только для диагностики)

`Verified by owner` имеет значение `yes`, только когда `Cross-signing verified` имеет значение `yes`; одного локального доверия или подписи владельца недостаточно.

`--allow-degraded-local-state` возвращает диагностические данные по мере возможности, не подготавливая предварительно учётную запись Matrix; это полезно для автономных или частично настроенных проверок.

### Верификация этого устройства с помощью ключа восстановления

Передавайте ключ восстановления через стандартный ввод, а не в командной строке:

```bash
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin
```

Команда сообщает о трёх состояниях:

- `Recovery key accepted`: Matrix принял ключ для хранилища секретов или установления доверия к устройству.
- `Backup usable`: резервную копию ключей комнат можно загрузить с использованием доверенного материала восстановления.
- `Device verified by owner`: это устройство пользуется полным доверием идентичности перекрёстной подписи Matrix.

Команда завершается с ненулевым кодом, если полное доверие к идентичности не установлено, даже если ключ восстановления разблокировал материалы резервной копии. В этом случае завершите самоверификацию в другом клиенте Matrix:

```bash
openclaw matrix verify self
```

`verify self` перед успешным завершением ожидает `Cross-signing verified: yes`. Используйте `--timeout-ms <ms>`, чтобы настроить время ожидания.

Форма с ключом в явном виде `openclaw matrix verify device "<recovery-key>"` также работает, но ключ сохраняется в истории оболочки.

### Инициализация или восстановление перекрёстной подписи

```bash
openclaw matrix verify bootstrap
```

Команда восстановления и настройки зашифрованных учётных записей. Она последовательно:

- инициализирует хранилище секретов, по возможности повторно используя существующий ключ восстановления
- инициализирует перекрёстную подпись и отправляет отсутствующие открытые ключи
- помечает и подписывает перекрёстной подписью текущее устройство
- создаёт серверную резервную копию ключей комнат, если она ещё не существует

Если домашний сервер требует UIA для отправки ключей перекрёстной подписи, OpenClaw сначала пытается выполнить операцию без аутентификации, затем с `m.login.dummy`, а затем с `m.login.password` (требуется `channels.matrix.password`).

Полезные флаги:

- `--recovery-key-stdin` (используйте вместе с `printf '%s\n' "$MATRIX_RECOVERY_KEY" | ...`) или `--recovery-key <key>`
- `--force-reset-cross-signing` для удаления текущей идентичности перекрёстной подписи (только намеренно; требуется активный ключ восстановления, сохранённый или переданный с помощью `--recovery-key-stdin`)

### Резервная копия ключей комнат

```bash
openclaw matrix verify backup status
printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
```

`backup status` показывает, существует ли серверная резервная копия и может ли это устройство её расшифровать. `backup restore` импортирует сохранённые в резервной копии ключи комнат в локальное криптографическое хранилище; опустите `--recovery-key-stdin`, если ключ восстановления уже сохранён на диске.

Чтобы заменить повреждённую резервную копию новой базовой версией (с согласием на потерю невосстановимой старой истории; при невозможности загрузить текущий секрет резервной копии также может быть заново создано хранилище секретов):

```bash
openclaw matrix verify backup reset --yes
```

Добавляйте `--rotate-recovery-key`, только если предыдущий ключ восстановления должен намеренно перестать разблокировать новую базовую резервную копию.

### Просмотр, отправка и обработка запросов верификации

```bash
openclaw matrix verify list
```

Выводит ожидающие запросы верификации для выбранной учётной записи.

```bash
openclaw matrix verify request --own-user
openclaw matrix verify request --user-id @ops:example.org --device-id ABCDEF
```

Отправляет запрос верификации от этой учётной записи. `--own-user` запрашивает самоверификацию (примите запрос в другом клиенте Matrix того же пользователя); `--user-id`/`--device-id`/`--room-id` предназначены для другого пользователя. `--own-user` нельзя сочетать с другими флагами выбора цели.

Для низкоуровневого управления жизненным циклом — обычно при отслеживании входящих запросов из другого клиента — следующие команды применяются к конкретному запросу `<id>` (выводится командами `verify list` и `verify request`):

| Команда                                    | Назначение                                                             |
| ------------------------------------------ | ------------------------------------------------------------------- |
| `openclaw matrix verify accept <id>`       | Принять входящий запрос                                           |
| `openclaw matrix verify start <id>`        | Запустить процесс SAS                                                  |
| `openclaw matrix verify sas <id>`          | Вывести эмодзи или десятичные числа SAS                                     |
| `openclaw matrix verify confirm-sas <id>`  | Подтвердить, что SAS совпадает с отображаемым в другом клиенте            |
| `openclaw matrix verify mismatch-sas <id>` | Отклонить SAS, если эмодзи или десятичные числа не совпадают              |
| `openclaw matrix verify cancel <id>`       | Отменить; принимает необязательные `--reason <text>` и `--code <matrix-code>` |

`accept`, `start`, `sas`, `confirm-sas`, `mismatch-sas` и `cancel` поддерживают `--user-id` и `--room-id` как подсказки для последующих действий в личных сообщениях, когда верификация привязана к определённой комнате личных сообщений.

### Примечания о нескольких учётных записях

Без `--account <id>` команды CLI Matrix используют неявную учётную запись по умолчанию. Если настроено несколько именованных учётных записей и параметр `channels.matrix.defaultAccount` не указан, команды не пытаются угадать выбор и предлагают выбрать учётную запись. Если E2EE отключено или недоступно для именованной учётной записи, ошибка указывает на ключ конфигурации этой учётной записи, например `channels.matrix.accounts.assistant.encryption`.

<AccordionGroup>
  <Accordion title="Поведение при запуске">
    При `encryption: true` значение `startupVerification` по умолчанию равно `"if-unverified"`. При запуске неверифицированное устройство запрашивает самоверификацию в другом клиенте Matrix, пропуская дубликаты и применяя период ожидания (по умолчанию 24 часа). Настройте его с помощью `startupVerificationCooldownHours` или отключите с помощью `startupVerification: "off"`.

    При запуске также выполняется консервативная инициализация криптографической системы с повторным использованием текущего хранилища секретов и идентичности перекрёстной подписи. Если состояние инициализации нарушено, OpenClaw пытается выполнить контролируемое восстановление даже без `channels.matrix.password`; если домашний сервер требует UIA с паролем, при запуске записывается предупреждение, но ошибка не становится критической. Устройства, уже подписанные владельцем, сохраняются.

    Полный процесс обновления см. в разделе [Миграция Matrix](/ru/channels/matrix-migration).

  </Accordion>

  <Accordion title="Уведомления о верификации">
    Matrix публикует уведомления о жизненном цикле верификации в строгой комнате личных сообщений для верификации в виде сообщений `m.notice`: запрос, готовность (с указанием "Verify by emoji"), начало и завершение, а также сведения SAS (эмодзи или десятичные числа), если они доступны.

    Входящие запросы из другого клиента Matrix отслеживаются и принимаются автоматически. Для самоверификации OpenClaw автоматически запускает процесс SAS и подтверждает свою сторону, как только становится доступна верификация по эмодзи — при этом необходимо сравнить значения и подтвердить "They match" в клиенте Matrix.

    Системные уведомления о верификации не передаются в конвейер чата агента.

  </Accordion>

  <Accordion title="Удалённое или недействительное устройство Matrix">
    Если `verify status` сообщает, что текущее устройство больше не числится на домашнем сервере, создайте новое устройство OpenClaw Matrix. Для входа по паролю:

```bash
openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --user-id '@assistant:example.org' \
  --password '<password>' \
  --device-name OpenClaw-Gateway
```

    Для аутентификации по токену создайте новый токен доступа в клиенте Matrix или интерфейсе администратора, затем обновите OpenClaw:

```bash
openclaw matrix account add \
  --account assistant \
  --homeserver https://matrix.example.org \
  --access-token '<token>'
```

    Замените `assistant` на идентификатор учётной записи из завершившейся с ошибкой команды или опустите `--account`, чтобы использовать учётную запись по умолчанию.

  </Accordion>

  <Accordion title="Гигиена устройств">
    Старые устройства, управляемые OpenClaw, могут накапливаться. Просмотрите список и удалите устаревшие:

```bash
openclaw matrix devices list
openclaw matrix devices prune-stale
```

  </Accordion>

  <Accordion title="Хранилище криптографических данных">
    Сквозное шифрование Matrix использует официальный путь криптографии Rust `matrix-js-sdk` с `fake-indexeddb` в качестве прослойки IndexedDB. Криптографическое состояние сохраняется в `crypto-idb-snapshot.json` (с ограничительными разрешениями файлов).

    Зашифрованное состояние среды выполнения находится в `~/.openclaw/matrix/accounts/<account>/<homeserver>__<user>/<token-hash>/` и включает хранилище синхронизации, хранилище криптографических данных, ключ восстановления, снимок IDB, привязки веток и состояние проверки при запуске. Когда токен изменяется, но идентификатор учётной записи остаётся прежним, OpenClaw повторно использует наиболее подходящий существующий корень, поэтому предыдущее состояние остаётся доступным.

    Единственный старый корень с хешем токена может быть нормальным путём сохранения непрерывности при ротации токена. Если OpenClaw регистрирует `matrix: multiple populated token-hash storage roots detected`, проверьте каталог учётной записи и архивируйте устаревшие соседние корни только после подтверждения работоспособности выбранного активного корня. Вместо немедленного удаления устаревших корней предпочтительно переместить их в каталог `_archive/`.

  </Accordion>
</AccordionGroup>

## Управление профилем

```bash
openclaw matrix profile set --name "OpenClaw Assistant"
openclaw matrix profile set --avatar-url https://cdn.example.org/avatar.png
```

Передайте оба параметра в одном вызове. Matrix принимает URL аватаров `mxc://` напрямую; передача `http://`/`https://` сначала загружает файл, а затем сохраняет разрешённый URL `mxc://` в `channels.matrix.avatarUrl` (или в переопределение для отдельной учётной записи).

## Ветки

Matrix поддерживает собственные ветки как для автоматических ответов, так и для отправки сообщений инструментом сообщений. Поведение контролируют два независимых параметра:

### Маршрутизация сеансов (`sessionScope`)

`dm.sessionScope` определяет, как комнаты личных сообщений Matrix сопоставляются с сеансами OpenClaw:

- `"per-user"` (по умолчанию): все комнаты личных сообщений с одним и тем же маршрутизируемым собеседником используют общий сеанс.
- `"per-room"`: каждая комната личных сообщений Matrix получает собственный ключ сеанса, даже для одного и того же собеседника.

Явные привязки бесед всегда имеют приоритет над `sessionScope`; привязанные комнаты и ветки сохраняют выбранный целевой сеанс.

### Ответы в ветках (`threadReplies`)

`threadReplies` определяет, где бот публикует ответ:

- `"off"`: ответы публикуются на верхнем уровне. Входящие сообщения из веток остаются в родительском сеансе.
- `"inbound"`: отвечать внутри ветки, только если входящее сообщение уже находилось в этой ветке.
- `"always"`: отвечать внутри ветки, корнем которой является инициировавшее сообщение; начиная с первого инициирующего сообщения эта беседа маршрутизируется через соответствующий сеанс, ограниченный веткой.

`dm.threadReplies` переопределяет это только для личных сообщений — например, позволяет изолировать ветки комнат, сохраняя личные сообщения без ветвления.

### Наследование веток и команды с косой чертой

- Входящие сообщения из веток включают корневое сообщение ветки как дополнительный контекст агента.
- Отправки инструментом сообщений автоматически наследуют текущую ветку Matrix при нацеливании на ту же комнату (или на того же пользователя личных сообщений), если явно не указан `threadId`.
- Повторное использование цели-пользователя личных сообщений применяется только тогда, когда метаданные текущего сеанса подтверждают того же собеседника личных сообщений в той же учётной записи Matrix; иначе OpenClaw возвращается к обычной маршрутизации, ограниченной пользователем.
- `/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` и привязанный к ветке `/acp spawn` работают в комнатах и личных сообщениях Matrix.
- Верхнеуровневый `/focus` создаёт новую ветку Matrix и привязывает её к целевому сеансу, если включён `threadBindings.spawnSessions`.
- Запуск `/focus` или `/acp spawn --thread here` внутри существующей ветки Matrix привязывает эту ветку на месте.

Когда OpenClaw обнаруживает конфликт комнаты личных сообщений Matrix с другой комнатой личных сообщений в том же общем сеансе, он публикует однократное уведомление `m.notice` со ссылкой на обходной путь `/focus` и предложением изменить `dm.sessionScope`. Уведомление появляется только при включённых привязках веток.

## Привязки бесед ACP

Комнаты, личные сообщения и существующие ветки Matrix могут становиться постоянными рабочими пространствами ACP без изменения интерфейса чата.

Быстрый процесс для оператора:

- Запустите `/acp spawn codex --bind here` внутри личных сообщений, комнаты или существующей ветки Matrix, чтобы продолжить использование.
- В верхнеуровневых личных сообщениях или комнате текущие личные сообщения или комната остаются интерфейсом чата, а будущие сообщения маршрутизируются в созданный сеанс ACP.
- Внутри существующей ветки `--bind here` привязывает текущую ветку на месте.
- `/new` и `/reset` сбрасывают тот же привязанный сеанс ACP на месте.
- `/acp close` закрывает сеанс ACP и удаляет привязку.

`--bind here` не создаёт дочернюю ветку Matrix. `threadBindings.spawnSessions` управляет доступностью `/acp spawn --thread auto|here`, где OpenClaw требуется создать или привязать дочернюю ветку.

### Конфигурация привязки веток

Matrix наследует глобальные значения по умолчанию из `session.threadBindings` и поддерживает переопределения для отдельных каналов:

- `threadBindings.enabled`
- `threadBindings.idleHours`
- `threadBindings.maxAgeHours`
- `threadBindings.spawnSessions`: управляет созданием веток как субагентами, так и ACP.
- `threadBindings.spawnSubagentSessions` / `threadBindings.spawnAcpSessions`: более узкие переопределения для создания веток только субагентами или только ACP.
- `threadBindings.defaultSpawnContext`

Создание сеансов, привязанных к веткам Matrix, включено по умолчанию. Установите `threadBindings.spawnSessions: false`, чтобы запретить верхнеуровневым `/focus` и `/acp spawn --thread auto|here` создавать или привязывать ветки Matrix. Установите `threadBindings.defaultSpawnContext: "isolated"`, если при создании собственных веток субагентов не следует разветвлять расшифровку родительского сеанса.

## Реакции

Matrix поддерживает исходящие реакции, уведомления о входящих реакциях и реакции-подтверждения.

Доступность инструментов исходящих реакций управляется `channels.matrix.actions.reactions`:

- `react` добавляет реакцию к событию Matrix.
- `reactions` выводит текущую сводку реакций для события Matrix.
- `emoji=""` удаляет собственные реакции бота на это событие.
- `remove: true` удаляет у бота только указанную реакцию-эмодзи.

**Порядок разрешения** (используется первое определённое значение):

| Настройка                 | Порядок                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------- |
| `ackReaction`           | для учётной записи -> канал -> `messages.ackReaction` -> резервный эмодзи идентичности агента   |
| `ackReactionScope`      | для учётной записи -> канал -> `messages.ackReactionScope` -> значение по умолчанию `"group-mentions"` |
| `reactionNotifications` | для учётной записи -> канал -> значение по умолчанию `"own"`                                           |

`reactionNotifications: "own"` пересылает добавленные события `m.reaction`, когда они относятся к сообщениям Matrix, созданным ботом; `"off"` отключает системные события реакций. Удаления реакций не преобразуются в системные события — Matrix представляет их как редактирования, а не как отдельные удаления `m.reaction`.

## Контекст истории

- `channels.matrix.historyLimit` определяет, сколько последних сообщений комнаты включается как `InboundHistory`, когда сообщение комнаты инициирует агента. Резервно используется `messages.groupChat.historyLimit`; если оба значения не заданы, фактическое значение по умолчанию — `0` (отключено).
- История комнат Matrix ограничена комнатой; личные сообщения продолжают использовать обычную историю сеанса.
- История комнаты содержит только ожидающие сообщения: OpenClaw буферизует сообщения комнаты, которые ещё не инициировали ответ, а затем создаёт снимок этого окна при поступлении упоминания или другого инициирующего события.
- Текущее инициирующее сообщение не включается в `InboundHistory`; для этого хода оно остаётся в основном теле входящего сообщения.
- Повторные попытки обработки одного и того же события Matrix используют исходный снимок истории, а не смещаются вперёд к более новым сообщениям комнаты.

## Видимость контекста

Matrix поддерживает общий параметр `contextVisibility` для дополнительного контекста комнаты, такого как полученный текст ответа, корни веток и ожидающая история.

- `contextVisibility: "all"` используется по умолчанию. Дополнительный контекст сохраняется в полученном виде.
- `contextVisibility: "allowlist"` фильтрует дополнительный контекст, оставляя отправителей, разрешённых активными проверками списков разрешённых комнат и пользователей.
- `contextVisibility: "allowlist_quote"` работает подобно `allowlist`, но сохраняет одну явно указанную цитату ответа.

Это влияет только на видимость дополнительного контекста, а не на возможность самого входящего сообщения инициировать ответ. Авторизация инициирования по-прежнему определяется `groupPolicy`, `groups`, `groupAllowFrom` и настройками политики личных сообщений.

## Политика личных сообщений и комнат

```json5
{
  channels: {
    matrix: {
      dm: {
        policy: "allowlist",
        allowFrom: ["@admin:example.org"],
        threadReplies: "off",
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
      groups: {
        "!roomid:example.org": { requireMention: true },
      },
    },
  },
}
```

Чтобы полностью отключить личные сообщения, сохранив работу комнат, установите `dm.enabled: false`:

```json5
{
  channels: {
    matrix: {
      dm: { enabled: false },
      groupPolicy: "allowlist",
      groupAllowFrom: ["@admin:example.org"],
    },
  },
}
```

Поведение ограничения по упоминаниям и списков разрешённых пользователей описано в разделе [Группы](/ru/channels/groups).

Пример сопряжения для личных сообщений Matrix:

```bash
openclaw pairing list matrix
openclaw pairing approve matrix <CODE>
```

Если неодобренный пользователь Matrix продолжает отправлять сообщения до одобрения, OpenClaw повторно использует тот же ожидающий код сопряжения и после короткого периода ожидания может отправить ответ-напоминание вместо создания нового кода.

Общий процесс сопряжения личных сообщений и структура хранилища описаны в разделе [Сопряжение](/ru/channels/pairing).

## Восстановление комнаты личных сообщений

Если состояние личных сообщений рассинхронизируется, у OpenClaw могут остаться устаревшие сопоставления `m.direct`, указывающие на старые одиночные комнаты вместо активных личных сообщений. Проверьте текущее сопоставление для собеседника:

```bash
openclaw matrix direct inspect --user-id @alice:example.org
```

Восстановите его:

```bash
openclaw matrix direct repair --user-id @alice:example.org
```

Обе команды принимают `--account <id>` для конфигураций с несколькими учётными записями. Процесс восстановления:

- предпочитает строгие личные сообщения 1:1, уже сопоставленные в `m.direct`
- резервно использует любые строгие личные сообщения 1:1 с этим пользователем, к которым выполнено текущее подключение
- создаёт новую комнату личных сообщений и перезаписывает `m.direct`, если работоспособных личных сообщений не существует

Старые комнаты не удаляются автоматически. Выбираются работоспособные личные сообщения, а сопоставление обновляется, чтобы будущие отправки Matrix, уведомления о проверке и другие процессы личных сообщений направлялись в правильную комнату.

## Одобрения выполнения

Matrix может выступать собственным клиентом одобрений. Настройте это в `channels.matrix.execApprovals` (или в `channels.matrix.accounts.<account>.execApprovals` для переопределения отдельной учётной записи):

- `enabled`: доставлять запросы на одобрение через собственные запросы Matrix. Неустановленное значение или `"auto"` автоматически включает доставку, когда удаётся определить хотя бы одного одобряющего; установите `false`, чтобы явно отключить её.
- `approvers`: идентификаторы пользователей Matrix (`@owner:example.org`), которым разрешено одобрять запросы выполнения. Резервно используется `channels.matrix.dm.allowFrom`.
- `target`: куда отправлять запросы. `"dm"` (по умолчанию) отправляет их в личные сообщения одобряющих; `"channel"` отправляет в исходную комнату или личные сообщения; `"both"` отправляет в оба места.
- `agentFilter` / `sessionFilter`: необязательные списки разрешённых агентов и сеансов, которые инициируют доставку через Matrix.

Авторизация немного различается для разных видов одобрений:

- **Одобрения выполнения** используют `execApprovals.approvers`, резервно обращаясь к `dm.allowFrom`.
- **Одобрения плагинов** авторизуются только через `dm.allowFrom`.

Оба типа поддерживают быстрые реакции Matrix и обновления сообщений. Утверждающие видят быстрые реакции в основном сообщении запроса на утверждение:

- ✅ разрешить один раз
- ❌ отклонить
- ♾️ разрешать всегда (если это допускает действующая политика выполнения)

Резервные слеш-команды: `/approve <id> allow-once`, `/approve <id> allow-always`, `/approve <id> deny`.

Утверждать или отклонять могут только распознанные утверждающие. Доставка запросов на утверждение выполнения в канал включает текст команды — включайте `channel` или `both` только в доверенных комнатах.

См. также: [Утверждения выполнения](/ru/tools/exec-approvals).

## Слеш-команды

Слеш-команды (`/new`, `/reset`, `/model`, `/focus`, `/unfocus`, `/agents`, `/session`, `/acp`, `/approve` и т. д.) работают непосредственно в личных сообщениях. В комнатах OpenClaw также распознаёт команды с предшествующим упоминанием собственного бота в Matrix, поэтому `@bot:server /new` запускает обработку команды без специального регулярного выражения для упоминаний — благодаря этому бот реагирует на характерные для комнат сообщения `@mention /command`, которые отправляют Element и аналогичные клиенты, когда пользователь дополняет имя бота клавишей Tab перед вводом команды.

Правила авторизации продолжают действовать: отправители команд должны соответствовать тем же политикам списка разрешённых пользователей или владельцев для личных сообщений либо комнат, что и отправители обычных сообщений.

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

```json5
{
  channels: {
    matrix: {
      enabled: true,
      defaultAccount: "assistant",
      dm: { policy: "pairing" },
      accounts: {
        assistant: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_assistant_xxx",
          encryption: true,
        },
        alerts: {
          homeserver: "https://matrix.example.org",
          accessToken: "syt_alerts_xxx",
          dm: {
            policy: "allowlist",
            allowFrom: ["@ops:example.org"],
            threadReplies: "off",
          },
        },
      },
    },
  },
}
```

**Наследование:**

- Значения `channels.matrix` верхнего уровня используются как значения по умолчанию для именованных учётных записей, если они не переопределены в учётной записи.
- Чтобы ограничить унаследованную запись комнаты определённой учётной записью, используйте `groups.<room>.account`. Записи без `account` являются общими для всех учётных записей; `account: "default"` продолжает работать, когда учётная запись по умолчанию настроена на верхнем уровне.

**Выбор учётной записи по умолчанию:**

- Задайте `defaultAccount`, чтобы выбрать именованную учётную запись, которой отдают предпочтение неявная маршрутизация, проверки и команды CLI.
- Если имеется несколько учётных записей и одна из них буквально называется `default`, OpenClaw неявно использует её, даже если `defaultAccount` не задан.
- Если имеется несколько именованных учётных записей, но учётная запись по умолчанию не выбрана, команды CLI не пытаются её угадать — задайте `defaultAccount` или передайте `--account <id>`.
- Блок `channels.matrix.*` верхнего уровня считается неявной учётной записью `default` только при полной настройке аутентификации (`homeserver` + `accessToken` или `homeserver` + `userId` + `password`). Именованные учётные записи остаются доступными для обнаружения по `homeserver` + `userId`, если сохранённых учётных данных достаточно для аутентификации.

**Преобразование:**

- Когда OpenClaw во время исправления или настройки преобразует конфигурацию с одной учётной записью в конфигурацию с несколькими, он сохраняет существующую именованную учётную запись, если она имеется или на неё уже указывает `defaultAccount`. В преобразованную учётную запись перемещаются только ключи аутентификации и начальной настройки Matrix; общие ключи политики доставки остаются на верхнем уровне.

Общий шаблон для нескольких учётных записей описан в [справочнике по конфигурации](/ru/gateway/config-channels#multi-account-all-channels).

## Частные и локальные домашние серверы

По умолчанию OpenClaw блокирует частные и внутренние домашние серверы Matrix для защиты от SSRF, если они не разрешены отдельно для учётной записи.

Если домашний сервер работает на localhost, IP-адресе локальной сети или Tailscale либо внутреннем имени хоста, включите `network.dangerouslyAllowPrivateNetwork` для этой учётной записи:

```json5
{
  channels: {
    matrix: {
      homeserver: "http://matrix-synapse:8008",
      network: {
        dangerouslyAllowPrivateNetwork: true,
      },
      accessToken: "syt_internal_xxx",
    },
  },
}
```

Пример настройки через CLI:

```bash
openclaw matrix account add \
  --account ops \
  --homeserver http://matrix-synapse:8008 \
  --allow-private-network \
  --access-token syt_ops_xxx
```

Это явное разрешение допускает только доверенные частные и внутренние адресаты. Общедоступные домашние серверы с незашифрованным подключением, такие как `http://matrix.example.org:8008`, по-прежнему блокируются. По возможности используйте `https://`.

## Проксирование трафика Matrix

Если развёртыванию Matrix требуется явный исходящий прокси-сервер HTTP(S), задайте `channels.matrix.proxy`:

```json5
{
  channels: {
    matrix: {
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
    },
  },
}
```

Именованные учётные записи могут переопределять значение верхнего уровня с помощью `channels.matrix.accounts.<id>.proxy`. OpenClaw использует одну и ту же настройку прокси-сервера для рабочего трафика Matrix и проверок состояния учётной записи.

## Разрешение адресатов

Matrix принимает следующие формы адресатов везде, где OpenClaw запрашивает комнату или пользователя:

- Пользователи: `@user:server`, `user:@user:server` или `matrix:user:@user:server`
- Комнаты: `!room:server`, `room:!room:server` или `matrix:room:!room:server`
- Псевдонимы: `#alias:server`, `channel:#alias:server` или `matrix:channel:#alias:server`

Идентификаторы комнат Matrix чувствительны к регистру. При настройке явных адресатов доставки, заданий Cron, привязок или списков разрешённых комнат используйте точный регистр идентификатора комнаты из Matrix. OpenClaw приводит внутренние ключи сеансов к каноническому виду для хранения, поэтому эти ключи в нижнем регистре не являются надёжным источником идентификаторов доставки Matrix.

Поиск в актуальном каталоге выполняется через учётную запись Matrix, в которую выполнен вход:

- При поиске пользователей запрашивается каталог пользователей Matrix на соответствующем домашнем сервере.
- При поиске комнат явные идентификаторы и псевдонимы комнат принимаются напрямую. Поиск по именам комнат, в которые выполнено присоединение, выполняется по возможности и применяется только к рабочим спискам разрешённых комнат, когда задан `dangerouslyAllowNameMatching: true`.
- Если имя комнаты невозможно разрешить в идентификатор или псевдоним, оно игнорируется при разрешении рабочего списка разрешённых комнат.

## Справочник по конфигурации

Поля пользователей со списками разрешений (`groupAllowFrom`, `dm.allowFrom`, `groups.<room>.users`) принимают полные идентификаторы пользователей Matrix — это самый безопасный вариант. По умолчанию записи, не являющиеся идентификаторами, игнорируются. Если задан `dangerouslyAllowNameMatching: true`, точные совпадения с отображаемыми именами в каталоге Matrix разрешаются при запуске и при каждом изменении списка разрешений во время работы монитора; неразрешимые записи игнорируются во время выполнения.

Ключами списка разрешённых комнат (`groups`, устаревший `rooms`) должны быть идентификаторы или псевдонимы комнат. По умолчанию ключи, содержащие простые имена комнат, игнорируются; `dangerouslyAllowNameMatching: true` восстанавливает поиск по возможности среди имён комнат, в которые выполнено присоединение.

### Учётная запись и подключение

- `enabled`: включение или отключение канала.
- `name`: необязательная отображаемая метка учётной записи.
- `defaultAccount`: предпочтительный идентификатор учётной записи, когда настроено несколько учётных записей Matrix.
- `accounts`: именованные переопределения для отдельных учётных записей. Значения `channels.matrix` верхнего уровня наследуются как значения по умолчанию.
- `homeserver`: URL домашнего сервера, например `https://matrix.example.org`.
- `network.dangerouslyAllowPrivateNetwork`: разрешает этой учётной записи подключаться к `localhost`, IP-адресам локальной сети или Tailscale либо внутренним именам хостов.
- `proxy`: необязательный URL прокси-сервера HTTP(S) для трафика Matrix. Поддерживается переопределение для отдельной учётной записи.
- `userId`: полный идентификатор пользователя Matrix (`@bot:example.org`).
- `accessToken`: токен доступа для аутентификации по токену. Поддерживаются значения в виде обычного текста и SecretRef от поставщиков переменных окружения, файлов и выполнения команд ([управление секретами](/ru/gateway/secrets)).
- `password`: пароль для входа с аутентификацией по паролю. Поддерживаются значения в виде обычного текста и SecretRef.
- `deviceId`: явно заданный идентификатор устройства Matrix.
- `deviceName`: отображаемое имя устройства, используемое при входе по паролю.
- `avatarUrl`: сохранённый URL собственного аватара для синхронизации профиля и обновлений `profile set`.
- `initialSyncLimit`: максимальное количество событий, получаемых при синхронизации во время запуска.

### Шифрование

- `encryption`: включение E2EE. По умолчанию: `false`.
- `startupVerification`: `"if-unverified"` (по умолчанию при включённом E2EE) или `"off"`. При запуске автоматически запрашивает самопроверку, если это устройство не проверено.
- `startupVerificationCooldownHours`: интервал ожидания перед следующим автоматическим запросом при запуске. По умолчанию: `24`.

### Доступ и политики

- `groupPolicy`: `"open"`, `"allowlist"` или `"disabled"`. По умолчанию: `"allowlist"`.
- `groupAllowFrom`: список разрешённых идентификаторов пользователей для трафика комнат.
- `mentionPatterns`: ограниченные по области регулярные выражения для упоминаний в комнатах. Объект с `{ mode: "allow"|"deny", allowIn: [roomId, ...], denyIn: [roomId, ...] }`. Определяет, применяются ли настроенные `agents.list[].groupChat.mentionPatterns` отдельно для каждой комнаты.
- `dm.enabled`: если установлено значение `false`, игнорировать все личные сообщения. По умолчанию: `true`.
- `dm.policy`: `"pairing"` (по умолчанию), `"allowlist"`, `"open"` или `"disabled"`. Применяется после того, как бот присоединился к комнате и классифицировал её как личный диалог; не влияет на обработку приглашений.
- `dm.allowFrom`: список разрешённых идентификаторов пользователей для трафика личных сообщений.
- `dm.sessionScope`: `"per-user"` (по умолчанию) или `"per-room"`.
- `dm.threadReplies`: переопределение цепочек ответов только для личных сообщений (`"off"`, `"inbound"`, `"always"`).
- `allowBots`: принимать сообщения от других настроенных учётных записей ботов Matrix (`true` или `"mentions"`).
- `allowlistOnly`: если установлено значение `true`, принудительно устанавливает для всех активных политик личных сообщений (кроме `"disabled"`) и групповых политик `"open"` значение `"allowlist"`. Не изменяет политики `"disabled"`.
- `dangerouslyAllowNameMatching`: если установлено значение `true`, разрешает поиск отображаемых имён в каталоге Matrix для записей списка разрешённых пользователей и поиск имён комнат, в которые выполнено присоединение, для ключей списка разрешённых комнат. Предпочтительно использовать полные идентификаторы `@user:server`, а также идентификаторы или псевдонимы комнат.
- `autoJoin`: `"always"`, `"allowlist"` или `"off"`. По умолчанию: `"off"`. Применяется ко всем приглашениям Matrix, включая приглашения в личные диалоги.
- `autoJoinAllowlist`: комнаты и псевдонимы, разрешённые, когда `autoJoin` имеет значение `"allowlist"`. Записи псевдонимов разрешаются через домашний сервер, а не через состояние, заявленное приглашающей комнатой.
- `contextVisibility`: видимость дополнительного контекста (`"all"` по умолчанию, `"allowlist"`, `"allowlist_quote"`).

### Поведение ответов

- `replyToMode`: `"off"` (по умолчанию), `"first"`, `"all"` или `"batched"`.
- `threadReplies`: `"off"` (значение по умолчанию верхнего уровня разрешается в `"inbound"`, если не задано явно), `"inbound"` или `"always"`.
- `threadBindings`: переопределения для отдельных каналов, управляющие маршрутизацией и жизненным циклом сеансов, привязанных к веткам.
- `streaming`: вложенный объект `{ mode, chunkMode, block: { enabled, coalesce }, preview: { toolProgress }, progress: { label, labels, maxLines, maxLineChars, toolProgress } }`. `mode` принимает значение `"off"` (по умолчанию), `"partial"`, `"quiet"` или `"progress"`. Устаревшие скалярные и логические варианты записи мигрируют с помощью `openclaw doctor --fix`.
- `streaming.block.enabled`: если задано значение `true`, завершённые блоки ассистента сохраняются как отдельные сообщения о ходе выполнения. По умолчанию: `false`.
- `markdown`: необязательная конфигурация отображения Markdown для исходящего текста.
- `responsePrefix`: необязательная строка, добавляемая в начало исходящих ответов.
- `textChunkLimit`: размер исходящего фрагмента в символах при значении `streaming.chunkMode: "length"`. По умолчанию: `4000`.
- `streaming.chunkMode`: `"length"` (по умолчанию, разделение по количеству символов) или `"newline"` (разделение по границам строк).
- `historyLimit`: количество последних сообщений комнаты, включаемых как `InboundHistory`, когда сообщение в комнате запускает агента. При отсутствии значения используется `messages.groupChat.historyLimit`; фактическое значение по умолчанию — `0` (отключено).
- `mediaMaxMb`: ограничение размера медиафайлов в МБ для исходящей отправки и обработки входящих данных. По умолчанию: `20`.

### Настройки реакций

- `ackReaction`: переопределение реакции подтверждения для этого канала или аккаунта.
- `ackReactionScope`: переопределение области действия (`"group-mentions"` по умолчанию, `"group-all"`, `"direct"`, `"all"`, `"none"`, `"off"`).
- `reactionNotifications`: режим уведомлений о входящих реакциях (`"own"` по умолчанию, `"off"`).

### Инструменты и переопределения для отдельных комнат

- `actions`: управление доступом к инструментам для отдельных действий (`messages`, `reactions`, `pins`, `profile`, `memberInfo`, `channelInfo`, `verification`).
- `groups`: карта политик для отдельных комнат. После разрешения для идентификации сеанса используется стабильный идентификатор комнаты. (`rooms` — устаревший псевдоним.)
  - `groups.<room>.account`: ограничивает одну унаследованную запись комнаты указанным аккаунтом.
  - `groups.<room>.enabled`: переключатель для отдельной комнаты. При значении `false` комната игнорируется так, как если бы её не было в карте.
  - `groups.<room>.requireMention`: переопределение требования упоминания на уровне канала для отдельной комнаты.
  - `groups.<room>.allowBots`: переопределение настройки уровня канала для отдельной комнаты (`true` или `"mentions"`).
  - `groups.<room>.botLoopProtection`: переопределение лимита защиты от циклов взаимодействия между ботами для отдельной комнаты.
  - `groups.<room>.users`: список разрешённых отправителей для отдельной комнаты.
  - `groups.<room>.tools`: переопределения разрешений и запретов инструментов для отдельной комнаты.
  - `groups.<room>.autoReply`: переопределение проверки упоминаний для отдельной комнаты. `true` отключает требования упоминания для этой комнаты; `false` снова принудительно включает их.
  - `groups.<room>.skills`: фильтр навыков для отдельной комнаты.
  - `groups.<room>.systemPrompt`: фрагмент системного запроса для отдельной комнаты.

### Настройки подтверждения выполнения

- `execApprovals.enabled`: доставляет запросы на подтверждение выполнения через встроенные запросы Matrix.
- `execApprovals.approvers`: идентификаторы пользователей Matrix, которым разрешено подтверждение. При отсутствии значения используется `dm.allowFrom`.
- `execApprovals.target`: `"dm"` (по умолчанию), `"channel"` или `"both"`.
- `execApprovals.agentFilter` / `execApprovals.sessionFilter`: необязательные списки разрешённых агентов или сеансов для доставки.

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

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