Mainstream messaging

Миграция Matrix

Переход с предыдущего общедоступного плагина 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, а также в качестве резервного механизма при запуске клиента 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 автоматически. Если в старой установке была зашифрованная история, хранившаяся только локально и ни разу не попавшая в резервную копию, некоторые старые зашифрованные сообщения могут остаться недоступными для чтения после обновления независимо от выбранного пути миграции.

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

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 --verboseopenclaw matrix verify backup status --verboseprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

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

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

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

bash

openclaw matrix verify backup reset --yesopenclaw matrix verify backup status --verboseopenclaw matrix verify status

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

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

Matrix: настройка канала и конфигурация.
Правила push-уведомлений Matrix: маршрутизация уведомлений.
Doctor: проверка работоспособности и автоматический запуск миграции.
Руководство по миграции: все пути миграции (переносы между компьютерами, импорт между системами).
Плагины: установка и регистрация плагинов.

Was this useful?