---
read_when:
    - Обновление существующей установки Matrix
    - Перенос зашифрованной истории Matrix и состояния устройства
summary: Как OpenClaw обновляет предыдущий плагин Matrix на месте, включая ограничения восстановления зашифрованного состояния и действия по ручному восстановлению.
title: Миграция Matrix
x-i18n:
    generated_at: "2026-07-13T17:53:00Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: 33d5ac134338c8032ca1507ceee6eade2d37b3c86f0045fb883304ad208cd5e5
    source_path: channels/matrix-migration.md
    workflow: 16
---

Переход с предыдущего общедоступного плагина `matrix` на текущую реализацию.

Для большинства пользователей переход уже предусмотрен:

- плагин остаётся `@openclaw/matrix`
- канал остаётся `matrix`
- ваша конфигурация остаётся в `channels.matrix`
- кешированные учётные данные остаются в `~/.openclaw/credentials/matrix/`
- состояние среды выполнения остаётся в `~/.openclaw/matrix/`

Вам не нужно переименовывать ключи конфигурации или переустанавливать плагин под новым именем.
Корневой пакет `openclaw` больше не включает код среды выполнения Matrix или зависимости Matrix SDK.
Если `openclaw channels status` показывает, что Matrix настроен, но
плагин не установлен, выполните `openclaw doctor --fix` или
`openclaw plugins install @openclaw/matrix`; не устанавливайте пакеты Matrix SDK
в корневой пакет OpenClaw.

## Что миграция выполняет автоматически

Миграция Matrix запускается при выполнении [`openclaw doctor --fix`](/ru/gateway/doctor), а также в качестве резервного механизма при запуске клиента Matrix, если рядом с его хранилищем SQLite всё ещё обнаруживается файловое вспомогательное состояние.

Автоматическая миграция включает:

- повторное использование кешированных учётных данных Matrix
- сохранение выбранной учётной записи и конфигурации `channels.matrix`
- импорт файлового вспомогательного состояния (кеша синхронизации `bot-storage.json`, `recovery-key.json`, `legacy-crypto-migration.json`, снимков IndexedDB) в состояние Matrix в SQLite; мигрированные файлы архивируются с суффиксом `.migrated`
- повторное использование наиболее полного существующего корневого каталога хранения хешей токенов для той же учётной записи Matrix, домашнего сервера, пользователя и устройства, если токен доступа впоследствии изменится

## Обновление с выпусков OpenClaw старше 2026.4

В выпусках вплоть до линейки 2026.6 также выполнялась миграция исходной плоской структуры
единого хранилища Matrix (`~/.openclaw/matrix/bot-storage.json` и
`~/.openclaw/matrix/crypto/`) и подготавливалось восстановление зашифрованного состояния из
старого криптографического хранилища Rust. Текущие выпуски больше не содержат эту миграцию.

Если вы обновляете установку, которая всё ещё использует плоскую структуру, сначала
обновитесь до выпуска 2026.6, выполните `openclaw doctor --fix` и один раз запустите Gateway,
чтобы выполнить миграцию плоского хранилища и всех восстанавливаемых ключей комнат. Затем обновитесь
до последнего выпуска.

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

## Рекомендуемый порядок обновления

1. Обновите OpenClaw и плагин Matrix обычным способом.
2. Выполните:

   ```bash
   openclaw doctor --fix
   ```

3. Запустите или перезапустите Gateway.
4. Проверьте текущее состояние проверки и резервного копирования:

   ```bash
   openclaw matrix verify status
   openclaw matrix verify backup status
   ```

5. Поместите ключ восстановления для восстанавливаемой учётной записи Matrix в отдельную переменную среды этой учётной записи. Для одной учётной записи по умолчанию подойдёт `MATRIX_RECOVERY_KEY`. Для нескольких учётных записей используйте отдельную переменную для каждой учётной записи, например `MATRIX_RECOVERY_KEY_ASSISTANT`, и добавьте к команде `--account assistant`.

6. Если OpenClaw сообщает, что требуется ключ восстановления, выполните команду для соответствующей учётной записи:

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

7. Если это устройство всё ещё не проверено, выполните команду для соответствующей учётной записи:

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

   Если ключ восстановления принят и резервная копия пригодна для использования, но `Cross-signing verified`
   по-прежнему имеет значение `no`, завершите самопроверку из другого клиента Matrix:

   ```bash
   openclaw matrix verify self
   ```

   Примите запрос в другом клиенте Matrix, сравните эмодзи или десятичные числа
   и введите `yes`, только если они совпадают. Команда ожидает полного доверия
   к идентичности Matrix, прежде чем сообщить об успешном выполнении.

8. Если вы намеренно отказываетесь от невосстанавливаемой старой истории и хотите создать новую исходную резервную копию для будущих сообщений, выполните:

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

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

9. Если резервной копии ключей на сервере ещё нет, создайте её для будущего восстановления:

   ```bash
   openclaw matrix verify bootstrap
   ```

## Распространённые сообщения и их значение

`Failed migrating legacy Matrix client storage: ...`

- Значение: резервный механизм на стороне клиента Matrix обнаружил файловое вспомогательное состояние, но импорт в SQLite завершился с ошибкой. OpenClaw отменяет завершённые перемещения и прерывает этот резервный процесс, а не запускается незаметно с новым хранилищем.
- Что делать: проверьте права доступа к файловой системе и возможные конфликты, сохраните старое состояние без изменений и повторите попытку после устранения ошибки.

`Matrix is installed from a custom path: ...`

- Значение: Matrix закреплён за установкой из локального пути, поэтому обновления основной ветки не заменяют его автоматически пакетом Matrix по умолчанию.
- Что делать: выполните переустановку с помощью `openclaw plugins install @openclaw/matrix`, когда захотите вернуться к плагину Matrix по умолчанию.

`Matrix is installed from a custom path that no longer exists: ...`

- Значение: запись об установке плагина указывает на локальный путь, которого больше нет.
- Что делать: выполните переустановку с помощью `openclaw plugins install @openclaw/matrix` или, если вы запускаете OpenClaw из рабочей копии репозитория, `openclaw plugins install ./path/to/local/matrix-plugin`. `openclaw doctor --fix` также может удалить устаревшие ссылки на плагин Matrix.

### Сообщения о ручном восстановлении

`openclaw matrix verify status` и `openclaw matrix verify backup status` выводят строку `Backup issue:` и инструкции `Next steps:`, если резервная копия ключей комнат на этом устройстве находится в неисправном состоянии:

| Проблема с резервной копией                                           | Значение                                           | Исправление                                                                                                                              |
| --------------------------------------------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `no room-key backup exists on the homeserver`                         | восстанавливать не из чего                         | `openclaw matrix verify bootstrap`, чтобы создать резервную копию ключей комнат                                                           |
| `backup decryption key is not loaded on this device`                  | ключ существует, но здесь не активен               | `openclaw matrix verify backup restore`; если ключ по-прежнему не загружается, передайте ключ восстановления через канал с помощью `--recovery-key-stdin` |
| `backup decryption key could not be loaded from secret storage (...)` | загрузка защищённого хранилища завершилась с ошибкой или не поддерживается | передайте ключ восстановления через канал: `printf '%s\n' "$MATRIX_RECOVERY_KEY" \| openclaw matrix verify backup restore --recovery-key-stdin` |
| `backup key mismatch (...)`                                           | сохранённый ключ не соответствует активной резервной копии на сервере | повторно выполните `verify backup restore --recovery-key-stdin` с ключом активной резервной копии на сервере или `verify backup reset --yes`, чтобы создать новую исходную копию |
| `backup signature chain is not trusted by this device`                | устройство ещё не доверяет цепочке перекрёстной подписи | `verify device --recovery-key-stdin`, затем `verify self` из другого проверенного клиента, если доверие всё ещё не установлено полностью |
| `backup exists but is not active on this device`                      | резервная копия на сервере существует, локальный сеанс неактивен | сначала проверьте устройство, затем повторно проверьте с помощью `openclaw matrix verify backup status` |
| `backup trust state could not be fully determined`                    | диагностика не дала однозначного результата        | `openclaw matrix verify status --verbose`                                                                                                 |

Другие ошибки восстановления:

`Matrix recovery key is required`

- Значение: вы попытались выполнить этап восстановления, не предоставив ключ восстановления, хотя он требовался.
- Что делать: повторно выполните команду с `--recovery-key-stdin`, например `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`.

`Invalid Matrix recovery key: ...`

- Значение: предоставленный ключ не удалось разобрать или он не соответствовал ожидаемому формату.
- Что делать: повторите попытку, используя точный ключ восстановления из клиента Matrix или экспорта ключа восстановления.

`Matrix recovery key was applied, but this device still lacks full Matrix identity trust.`

- Значение: ключ восстановления открыл пригодные для использования данные резервной копии, но Matrix не установил полное доверие к идентичности посредством перекрёстной подписи для этого устройства. Проверьте вывод команды на наличие `Recovery key accepted`, `Backup usable`, `Cross-signing verified` и `Device verified by owner`.
- Что делать: выполните `openclaw matrix verify self`, примите запрос в другом клиенте Matrix, сравните SAS и введите `yes`, только если они совпадают. Используйте `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing`, только если намеренно хотите заменить текущую идентичность перекрёстной подписи.

Если вы согласны потерять невосстанавливаемую старую зашифрованную историю, вместо этого можно сбросить
текущую исходную резервную копию с помощью `openclaw matrix verify backup reset --yes`. Если
сохранённый секрет резервной копии повреждён, этот сброс также восстановит защищённое хранилище, чтобы
новый ключ резервной копии мог корректно загрузиться после перезапуска.

## Если зашифрованная история всё ещё не восстановилась

Выполните следующие проверки по порядку:

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

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

## Если вы хотите начать заново для будущих сообщений

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

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

Если после этого устройство всё ещё не проверено, завершите проверку из клиента Matrix: сравните эмодзи SAS или десятичные коды и подтвердите, что они совпадают.

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

- [Matrix](/ru/channels/matrix): настройка канала и конфигурация.
- [Правила push-уведомлений Matrix](/ru/channels/matrix-push-rules): маршрутизация уведомлений.
- [Doctor](/ru/gateway/doctor): проверка работоспособности и автоматический запуск миграции.
- [Руководство по миграции](/ru/install/migrating): все пути миграции (переносы между компьютерами, импорт между системами).
- [Плагины](/ru/tools/plugin): установка и регистрация плагинов.