--- read_when: - Оновлення наявної інсталяції Matrix - Перенесення зашифрованої історії Matrix і стану пристрою summary: Як OpenClaw оновлює попередній Matrix Plugin на місці, включно з обмеженнями відновлення зашифрованого стану та кроками ручного відновлення. title: Міграція Matrix x-i18n: generated_at: "2026-05-02T21:04:42Z" model: gpt-5.5 provider: openai source_hash: 8bc9b875fef0ae08978061a9fc7cbb076617009d79487ca8329e03076103b32c source_path: channels/matrix-migration.md workflow: 16 --- Оновлення з попереднього публічного Plugin `matrix` до поточної реалізації. Для більшості користувачів оновлення виконується на місці: - Plugin залишається `@openclaw/matrix` - канал залишається `matrix` - ваша конфігурація залишається в `channels.matrix` - кешовані облікові дані залишаються в `~/.openclaw/credentials/matrix/` - стан виконання залишається в `~/.openclaw/matrix/` Вам не потрібно перейменовувати ключі конфігурації або перевстановлювати Plugin під новою назвою. ## Що міграція робить автоматично Коли запускається Gateway, а також коли ви запускаєте [`openclaw doctor --fix`](/uk/gateway/doctor), OpenClaw намагається автоматично відновити старий стан Matrix. Перед тим як будь-який дієвий крок міграції Matrix змінює стан на диску, OpenClaw створює або повторно використовує цільовий знімок відновлення. Коли ви використовуєте `openclaw update`, точний тригер залежить від того, як установлено OpenClaw: - встановлення з вихідного коду запускають `openclaw doctor --fix` під час процесу оновлення, а потім за замовчуванням перезапускають Gateway - встановлення через менеджер пакетів оновлюють пакет, запускають неінтерактивний прохід doctor, а потім покладаються на стандартний перезапуск Gateway, щоб запуск міг завершити міграцію Matrix - якщо ви використовуєте `openclaw update --no-restart`, міграція Matrix, що виконується під час запуску, відкладається, доки ви пізніше не запустите `openclaw doctor --fix` і не перезапустите Gateway Автоматична міграція охоплює: - створення або повторне використання знімка перед міграцією в `~/Backups/openclaw-migrations/` - повторне використання ваших кешованих облікових даних Matrix - збереження того самого вибору облікового запису й конфігурації `channels.matrix` - переміщення найстарішого плоского сховища синхронізації Matrix у поточне розташування, прив’язане до облікового запису - переміщення найстарішого плоского криптосховища Matrix у поточне розташування, прив’язане до облікового запису, коли цільовий обліковий запис можна безпечно визначити - витягування раніше збереженого ключа розшифрування резервної копії ключів кімнат Matrix зі старого rust-криптосховища, коли цей ключ існує локально - повторне використання найповнішого наявного кореня сховища з хешем токена для того самого облікового запису Matrix, homeserver і користувача, коли access token згодом змінюється - сканування сусідніх коренів сховища з хешем токена на наявність метаданих очікуваного відновлення зашифрованого стану, коли access token Matrix змінився, але ідентичність облікового запису/пристрою залишилася тією самою - відновлення резервних копій ключів кімнат у нове криптосховище під час наступного запуску Matrix Деталі знімка: - OpenClaw записує файл-маркер у `~/.openclaw/matrix/migration-snapshot.json` після успішного знімка, щоб подальші проходи запуску й відновлення могли повторно використати той самий архів. - Ці автоматичні знімки міграції Matrix створюють резервну копію лише конфігурації + стану (`includeWorkspace: false`). - Якщо Matrix має лише попереджувальний стан міграції, наприклад через те, що `userId` або `accessToken` усе ще відсутні, OpenClaw ще не створює знімок, бо жодна зміна Matrix не є дієвою. - Якщо крок знімка не вдається, OpenClaw пропускає міграцію Matrix для цього запуску замість того, щоб змінювати стан без точки відновлення. Про оновлення з кількома обліковими записами: - найстаріше плоске сховище Matrix (`~/.openclaw/matrix/bot-storage.json` і `~/.openclaw/matrix/crypto/`) походить із макета з одним сховищем, тому OpenClaw може мігрувати його лише в одну визначену ціль облікового запису Matrix - уже прив’язані до облікового запису застарілі сховища Matrix виявляються й готуються окремо для кожного налаштованого облікового запису Matrix ## Що міграція не може зробити автоматично Попередній публічний Matrix Plugin **не** створював автоматично резервні копії ключів кімнат Matrix. Він зберігав локальний криптографічний стан і запитував перевірку пристрою, але не гарантував, що ваші ключі кімнат були зарезервовані на homeserver. Це означає, що деякі зашифровані встановлення можна мігрувати лише частково. OpenClaw не може автоматично відновити: - ключі кімнат, що існували лише локально й ніколи не були зарезервовані - зашифрований стан, коли цільовий обліковий запис Matrix ще не можна визначити, бо `homeserver`, `userId` або `accessToken` усе ще недоступні - автоматичну міграцію одного спільного плоского сховища Matrix, коли налаштовано кілька облікових записів Matrix, але `channels.matrix.defaultAccount` не задано - встановлення Plugin за користувацьким шляхом, які прив’язані до шляху репозиторію замість стандартного пакета Matrix - відсутній ключ відновлення, коли старе сховище мало зарезервовані ключі, але не зберегло ключ розшифрування локально Поточна область попереджень: - встановлення Matrix Plugin за користувацьким шляхом показуються як під час запуску Gateway, так і через `openclaw doctor` Якщо ваша стара інсталяція мала локальну зашифровану історію, для якої ніколи не створювали резервну копію, деякі старіші зашифровані повідомлення можуть залишитися нечитабельними після оновлення. ## Рекомендований процес оновлення 1. Оновіть OpenClaw і Matrix Plugin звичайним способом. Надавайте перевагу простому `openclaw update` без `--no-restart`, щоб запуск міг одразу завершити міграцію Matrix. 2. Запустіть: ```bash openclaw doctor --fix ``` Якщо Matrix має дієву роботу міграції, doctor спочатку створить або повторно використає знімок перед міграцією та виведе шлях до архіву. 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` лише тоді, коли вони збігаються. Команда завершується успішно лише після того, як `Cross-signing verified` стане `yes`. 8. Якщо ви свідомо відмовляєтеся від невідновлюваної старої історії й хочете створити свіжу базову резервну копію для майбутніх повідомлень, запустіть: ```bash openclaw matrix verify backup reset --yes ``` 9. Якщо серверної резервної копії ключів ще не існує, створіть її для майбутніх відновлень: ```bash openclaw matrix verify bootstrap ``` ## Як працює міграція зашифрованих даних Міграція зашифрованих даних — це двоетапний процес: 1. Запуск або `openclaw doctor --fix` створює чи повторно використовує знімок перед міграцією, якщо міграція зашифрованих даних є дієвою. 2. Запуск або `openclaw doctor --fix` перевіряє старе криптосховище Matrix через активну інсталяцію Matrix Plugin. 3. Якщо знайдено ключ розшифрування резервної копії, OpenClaw записує його в новий потік ключа відновлення й позначає відновлення ключів кімнат як очікуване. 4. Під час наступного запуску Matrix OpenClaw автоматично відновлює зарезервовані ключі кімнат у нове криптосховище. Якщо старе сховище повідомляє про ключі кімнат, які ніколи не були зарезервовані, OpenClaw попереджає, а не вдає, що відновлення успішне. ## Поширені повідомлення та їх значення ### Повідомлення про оновлення й виявлення `Matrix plugin upgraded in place.` - Значення: старий стан Matrix на диску було виявлено й мігровано в поточний макет. - Що робити: нічого, якщо той самий вивід також не містить попереджень. `Matrix migration snapshot created before applying Matrix upgrades.` - Значення: OpenClaw створив архів відновлення перед зміною стану Matrix. - Що робити: збережіть виведений шлях до архіву, доки не підтвердите, що міграція успішна. `Matrix migration snapshot reused before applying Matrix upgrades.` - Значення: OpenClaw знайшов наявний маркер знімка міграції Matrix і повторно використав цей архів замість створення дубліката резервної копії. - Що робити: збережіть виведений шлях до архіву, доки не підтвердите, що міграція успішна. `Legacy Matrix state detected at ... but channels.matrix is not configured yet.` - Значення: старий стан Matrix існує, але OpenClaw не може зіставити його з поточним обліковим записом Matrix, бо Matrix не налаштовано. - Що робити: налаштуйте `channels.matrix`, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Legacy Matrix state detected at ... but the new account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).` - Значення: OpenClaw знайшов старий стан, але все ще не може визначити точний поточний корінь облікового запису/пристрою. - Що робити: один раз запустіть Gateway із робочим входом Matrix або повторно запустіть `openclaw doctor --fix` після появи кешованих облікових даних. `Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.` - Значення: OpenClaw знайшов одне спільне плоске сховище Matrix, але відмовляється вгадувати, який іменований обліковий запис Matrix має його отримати. - Що робити: задайте `channels.matrix.defaultAccount` для потрібного облікового запису, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Matrix legacy sync store not migrated because the target already exists (...)` - Значення: нове розташування, прив’язане до облікового запису, вже має сховище синхронізації або криптосховище, тому OpenClaw не перезаписав його автоматично. - Що робити: переконайтеся, що поточний обліковий запис правильний, перш ніж вручну видаляти або переміщувати конфліктну ціль. `Failed migrating Matrix legacy sync store (...)` або `Failed migrating Matrix legacy crypto store (...)` - Значення: OpenClaw спробував перемістити старий стан Matrix, але файлова операція не вдалася. - Що робити: перевірте дозволи файлової системи й стан диска, потім повторно запустіть `openclaw doctor --fix`. `Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.` - Значення: OpenClaw знайшов старе зашифроване сховище Matrix, але немає поточної конфігурації Matrix, до якої його можна прив’язати. - Що робити: налаштуйте `channels.matrix`, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Legacy Matrix encrypted state detected at ... but the account-scoped target could not be resolved yet (need homeserver, userId, and access token for channels.matrix...).` - Значення: зашифроване сховище існує, але OpenClaw не може безпечно вирішити, до якого поточного облікового запису/пристрою воно належить. - Що робити: один раз запустіть Gateway із робочим входом Matrix або повторно запустіть `openclaw doctor --fix` після появи кешованих облікових даних. `Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.` - Значення: OpenClaw знайшов одне спільне плоске застаріле криптосховище, але відмовляється вгадувати, який іменований обліковий запис Matrix має його отримати. - Що робити: задайте `channels.matrix.defaultAccount` для потрібного облікового запису, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.` - Значення: OpenClaw виявив старий стан Matrix, але міграція все ще заблокована через відсутні дані ідентичності або облікових даних. - Що робити: завершіть вхід у Matrix або налаштування конфігурації, потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Legacy Matrix encrypted state was detected, but the Matrix plugin helper is unavailable. Install or repair @openclaw/matrix so OpenClaw can inspect the old rust crypto store before upgrading.` - Значення: OpenClaw знайшов старий зашифрований стан Matrix, але не зміг завантажити допоміжну точку входу з Matrix Plugin, яка зазвичай перевіряє це сховище. - Що робити: перевстановіть або відновіть Matrix Plugin (`openclaw plugins install @openclaw/matrix` або `openclaw plugins install ./path/to/local/matrix-plugin` для checkout репозиторію), потім повторно запустіть `openclaw doctor --fix` або перезапустіть Gateway. `Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.` - Значення: OpenClaw знайшов шлях до допоміжного файла, який виходить за межі кореня plugin або не проходить перевірки меж plugin, тому відмовився його імпортувати. - Що робити: перевстановіть Matrix plugin з довіреного шляху, потім повторно запустіть `openclaw doctor --fix` або перезапустіть gateway. `- Failed creating a Matrix migration snapshot before repair: ...` `- Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".` - Значення: OpenClaw відмовився змінювати стан Matrix, бо спочатку не зміг створити знімок для відновлення. - Що робити: усуньте помилку резервного копіювання, потім повторно запустіть `openclaw doctor --fix` або перезапустіть gateway. `Failed migrating legacy Matrix client storage: ...` - Значення: резервний механізм на боці клієнта Matrix знайшов старе пласке сховище, але переміщення не вдалося. Тепер OpenClaw перериває цей резервний шлях замість того, щоб мовчки запускатися з новим порожнім сховищем. - Що робити: перевірте права доступу до файлової системи або конфлікти, збережіть старий стан без змін і повторіть спробу після виправлення помилки. `Matrix is installed from a custom path: ...` - Значення: Matrix закріплено як встановлення зі шляху, тому основні оновлення не замінюють його автоматично стандартним пакетом Matrix з репозиторію. - Що робити: перевстановіть за допомогою `openclaw plugins install @openclaw/matrix`, коли захочете повернутися до стандартного Matrix plugin. ### Повідомлення відновлення зашифрованого стану `matrix: restored X/Y room key(s) from legacy encrypted-state backup` - Значення: резервні копії ключів кімнат успішно відновлено в нове криптосховище. - Що робити: зазвичай нічого. `matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically` - Значення: деякі старі ключі кімнат існували лише у старому локальному сховищі й ніколи не були завантажені до резервної копії Matrix. - Що робити: очікуйте, що частина старої зашифрованої історії залишиться недоступною, якщо ви не зможете вручну відновити ці ключі з іншого перевіреного клієнта. `Legacy Matrix encrypted state for account "..." has backed-up room keys, but no local backup decryption key was found. Ask the operator to run "openclaw matrix verify backup restore --recovery-key-stdin" after upgrade if they have the recovery key.` - Значення: резервна копія існує, але OpenClaw не зміг автоматично відновити ключ відновлення. - Що робити: запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. `Failed inspecting legacy Matrix encrypted state for account "..." (...): ...` - Значення: OpenClaw знайшов старе зашифроване сховище, але не зміг перевірити його достатньо безпечно, щоб підготувати відновлення. - Що робити: повторно запустіть `openclaw doctor --fix`. Якщо це повториться, збережіть старий каталог стану без змін і виконайте відновлення за допомогою іншого перевіреного клієнта Matrix плюс `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. `Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.` - Значення: OpenClaw виявив конфлікт ключів резервної копії та відмовився автоматично перезаписати поточний файл recovery-key. - Що робити: перевірте, який ключ відновлення правильний, перш ніж повторювати будь-яку команду відновлення. `Legacy Matrix encrypted state for account "..." cannot be fully converted automatically because the old rust crypto store does not expose all local room keys for export.` - Значення: це жорстке обмеження старого формату сховища. - Що робити: ключі з резервної копії все ще можна відновити, але локальна зашифрована історія може залишитися недоступною. `matrix: failed restoring room keys from legacy encrypted-state backup: ...` - Значення: новий plugin спробував відновлення, але Matrix повернув помилку. - Що робити: запустіть `openclaw matrix verify backup status`, потім за потреби повторіть спробу з `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. ### Повідомлення ручного відновлення `Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.` - Значення: OpenClaw знає, що у вас має бути ключ резервної копії, але він не активний на цьому пристрої. - Що робити: запустіть `openclaw matrix verify backup restore` або встановіть `MATRIX_RECOVERY_KEY` і за потреби запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin`. `Store a recovery key with 'openclaw matrix verify device --recovery-key-stdin', then run 'openclaw matrix verify backup restore'.` - Значення: на цьому пристрої зараз не збережено ключ відновлення. - Що робити: встановіть `MATRIX_RECOVERY_KEY`, запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`, потім відновіть резервну копію. `Backup key mismatch on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin' with the matching recovery key.` - Значення: збережений ключ не відповідає активній резервній копії Matrix. - Що робити: встановіть `MATRIX_RECOVERY_KEY` у правильний ключ і запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. Якщо ви погоджуєтеся втратити стару зашифровану історію, яку неможливо відновити, натомість можна скинути поточну базову лінію резервної копії за допомогою `openclaw matrix verify backup reset --yes`. Коли збережений секрет резервної копії пошкоджено, це скидання також може повторно створити secret storage, щоб новий ключ резервної копії міг коректно завантажитися після перезапуску. `Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin'.` - Значення: резервна копія існує, але цей пристрій ще недостатньо довіряє ланцюжку кроспідписування. - Що робити: встановіть `MATRIX_RECOVERY_KEY` і запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. `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 або файла recovery-key. `Matrix recovery key was applied, but this device still lacks full Matrix identity trust.` - Значення: OpenClaw зміг застосувати ключ відновлення, але Matrix досі не встановив повну довіру до ідентичності кроспідписування для цього пристрою. Перевірте вивід команди на наявність `Recovery key accepted`, `Backup usable`, `Cross-signing verified` і `Device verified by owner`. - Що робити: запустіть `openclaw matrix verify self`, прийміть запит в іншому клієнті Matrix, порівняйте SAS і введіть `yes` лише якщо він збігається. Команда очікує повної довіри до ідентичності Matrix перед повідомленням про успіх. Використовуйте `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing` лише тоді, коли ви навмисно хочете замінити поточну ідентичність кроспідписування. `Matrix key backup is not active on this device after loading from secret storage.` - Значення: secret storage не створило активний сеанс резервної копії на цьому пристрої. - Що робити: спочатку перевірте пристрій, потім повторно перевірте за допомогою `openclaw matrix verify backup status`. `Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device --recovery-key-stdin' first.` - Значення: цей пристрій не може відновлюватися з secret storage, доки перевірку пристрою не буде завершено. - Що робити: спочатку запустіть `printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin`. ### Повідомлення встановлення користувацького plugin `Matrix is installed from a custom path that no longer exists: ...` - Значення: запис встановлення вашого plugin вказує на локальний шлях, якого вже немає. - Що робити: перевстановіть за допомогою `openclaw plugins install @openclaw/matrix` або, якщо ви запускаєте з checkout репозиторію, `openclaw plugins install ./path/to/local/matrix-plugin`. ## Якщо зашифрована історія все ще не повертається Запустіть ці перевірки по порядку: ```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 ``` Якщо резервна копія відновлюється успішно, але в деяких старих кімнатах усе ще бракує історії, ці відсутні ключі, ймовірно, ніколи не були збережені в резервній копії попереднім plugin. ## Якщо ви хочете почати заново для майбутніх повідомлень Якщо ви погоджуєтеся втратити стару зашифровану історію, яку неможливо відновити, і хочете лише чисту базову лінію резервної копії надалі, запустіть ці команди по порядку: ```bash openclaw matrix verify backup reset --yes openclaw matrix verify backup status --verbose openclaw matrix verify status ``` Якщо після цього пристрій усе ще не перевірено, завершіть перевірку з вашого клієнта Matrix, порівнявши емодзі SAS або десяткові коди й підтвердивши, що вони збігаються. ## Пов’язане - [Matrix](/uk/channels/matrix): налаштування каналу й конфігурація. - [Правила push Matrix](/uk/channels/matrix-push-rules): маршрутизація сповіщень. - [Doctor](/uk/gateway/doctor): перевірка стану та автоматичний тригер міграції. - [Посібник із міграції](/uk/install/migrating): усі шляхи міграції (перенесення між машинами, імпорт між системами). - [Plugins](/uk/tools/plugin): встановлення та реєстрація plugin.