Langsung ke konten utama

​
Migrasi Matrix

Halaman ini membahas upgrade dari plugin publik matrix sebelumnya ke implementasi saat ini. Bagi sebagian besar pengguna, upgrade dilakukan secara in-place:
  • plugin tetap @openclaw/matrix
  • channel tetap matrix
  • konfigurasi Anda tetap berada di bawah channels.matrix
  • kredensial cache tetap berada di ~/.openclaw/credentials/matrix/
  • state runtime tetap berada di ~/.openclaw/matrix/
Anda tidak perlu mengganti nama key konfigurasi atau menginstal ulang plugin dengan nama baru.

​
Apa yang dilakukan migrasi secara otomatis

Saat gateway dimulai, dan saat Anda menjalankan openclaw doctor --fix, OpenClaw mencoba memperbaiki state Matrix lama secara otomatis. Sebelum langkah migrasi Matrix yang dapat ditindaklanjuti memutasi state di disk, OpenClaw membuat atau menggunakan kembali recovery snapshot yang terfokus. Saat Anda menggunakan openclaw update, pemicu yang tepat bergantung pada cara OpenClaw diinstal:
  • instalasi source menjalankan openclaw doctor --fix selama alur pembaruan, lalu me-restart gateway secara default
  • instalasi package manager memperbarui paket, menjalankan doctor pass non-interaktif, lalu mengandalkan restart gateway default agar startup dapat menyelesaikan migrasi Matrix
  • jika Anda menggunakan openclaw update --no-restart, migrasi Matrix berbasis startup ditunda sampai nanti Anda menjalankan openclaw doctor --fix dan me-restart gateway
Migrasi otomatis mencakup:
  • membuat atau menggunakan kembali snapshot pra-migrasi di bawah ~/Backups/openclaw-migrations/
  • menggunakan kembali kredensial Matrix cache Anda
  • mempertahankan pemilihan akun yang sama dan konfigurasi channels.matrix
  • memindahkan sync store Matrix flat tertua ke lokasi saat ini yang dicakup per akun
  • memindahkan crypto store Matrix flat tertua ke lokasi saat ini yang dicakup per akun ketika akun target dapat di-resolve dengan aman
  • mengekstrak backup decryption key room-key Matrix yang sebelumnya disimpan dari rust crypto store lama, ketika key tersebut ada secara lokal
  • menggunakan kembali root penyimpanan token-hash yang paling lengkap untuk akun Matrix, homeserver, dan pengguna yang sama saat access token berubah di kemudian hari
  • memindai root penyimpanan token-hash sibling untuk metadata restore state terenkripsi yang tertunda saat access token Matrix berubah tetapi identitas akun/perangkat tetap sama
  • memulihkan room key yang dicadangkan ke crypto store baru pada startup Matrix berikutnya
Detail snapshot:
  • OpenClaw menulis marker file di ~/.openclaw/matrix/migration-snapshot.json setelah snapshot berhasil sehingga pass startup dan perbaikan berikutnya dapat menggunakan kembali arsip yang sama.
  • Snapshot migrasi Matrix otomatis ini hanya mencadangkan konfigurasi + state (includeWorkspace: false).
  • Jika Matrix hanya memiliki state migrasi yang sebatas peringatan, misalnya karena userId atau accessToken masih belum ada, OpenClaw belum membuat snapshot karena belum ada mutasi Matrix yang dapat ditindaklanjuti.
  • Jika langkah snapshot gagal, OpenClaw melewati migrasi Matrix untuk run tersebut alih-alih memutasi state tanpa titik pemulihan.
Tentang upgrade multi-akun:
  • store Matrix flat tertua (~/.openclaw/matrix/bot-storage.json dan ~/.openclaw/matrix/crypto/) berasal dari layout single-store, sehingga OpenClaw hanya dapat memigrasikannya ke satu target akun Matrix yang berhasil di-resolve
  • store Matrix lama yang sudah dicakup per akun dideteksi dan disiapkan per akun Matrix yang dikonfigurasi

​
Apa yang tidak dapat dilakukan migrasi secara otomatis

Plugin Matrix publik sebelumnya tidak otomatis membuat backup room-key Matrix. Plugin tersebut menyimpan state crypto lokal dan meminta verifikasi perangkat, tetapi tidak menjamin bahwa room key Anda dicadangkan ke homeserver. Itu berarti beberapa instalasi terenkripsi hanya dapat dimigrasikan sebagian. OpenClaw tidak dapat memulihkan secara otomatis:
  • room key khusus lokal yang tidak pernah dicadangkan
  • state terenkripsi ketika akun Matrix target belum dapat di-resolve karena homeserver, userId, atau accessToken masih belum tersedia
  • migrasi otomatis satu store Matrix flat bersama ketika beberapa akun Matrix dikonfigurasi tetapi channels.matrix.defaultAccount tidak disetel
  • instalasi path plugin kustom yang dipin ke path repo alih-alih package Matrix standar
  • recovery key yang hilang ketika store lama memiliki key yang dicadangkan tetapi tidak menyimpan decryption key secara lokal
Cakupan peringatan saat ini:
  • instalasi path plugin Matrix kustom ditampilkan oleh startup gateway maupun openclaw doctor
Jika instalasi lama Anda memiliki riwayat terenkripsi khusus lokal yang tidak pernah dicadangkan, beberapa pesan terenkripsi lama mungkin tetap tidak dapat dibaca setelah upgrade.

​
Alur upgrade yang direkomendasikan

  1. Perbarui OpenClaw dan plugin Matrix seperti biasa. Sebaiknya gunakan openclaw update biasa tanpa --no-restart agar startup dapat langsung menyelesaikan migrasi Matrix.
  2. Jalankan: 
    openclaw doctor --fix
    Jika Matrix memiliki pekerjaan migrasi yang dapat ditindaklanjuti, doctor akan membuat atau menggunakan kembali snapshot pra-migrasi terlebih dahulu dan mencetak path arsipnya.
  3. Mulai atau restart gateway.
  4. Periksa status verifikasi dan backup saat ini: 
    openclaw matrix verify status
openclaw matrix verify backup status
  5. Jika OpenClaw memberi tahu bahwa recovery key diperlukan, jalankan: 
    openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
  6. Jika perangkat ini masih belum terverifikasi, jalankan: 
    openclaw matrix verify device "<your-recovery-key>"
  7. Jika Anda memang meninggalkan riwayat lama yang tidak dapat dipulihkan dan ingin baseline backup baru untuk pesan mendatang, jalankan: 
    openclaw matrix verify backup reset --yes
  8. Jika belum ada server-side key backup, buat satu untuk pemulihan di masa mendatang: 
    openclaw matrix verify bootstrap

​
Cara kerja migrasi terenkripsi

Migrasi terenkripsi adalah proses dua tahap:
  1. Startup atau openclaw doctor --fix membuat atau menggunakan kembali snapshot pra-migrasi jika migrasi terenkripsi dapat ditindaklanjuti.
  2. Startup atau openclaw doctor --fix memeriksa crypto store Matrix lama melalui instalasi plugin Matrix aktif.
  3. Jika backup decryption key ditemukan, OpenClaw menuliskannya ke alur recovery-key baru dan menandai restore room-key sebagai tertunda.
  4. Pada startup Matrix berikutnya, OpenClaw secara otomatis memulihkan room key yang dicadangkan ke crypto store baru.
Jika store lama melaporkan room key yang tidak pernah dicadangkan, OpenClaw memberi peringatan alih-alih berpura-pura bahwa pemulihan berhasil.

​
Pesan umum dan artinya

​
Pesan upgrade dan deteksi

Matrix plugin upgraded in place.
  • Arti: state Matrix lama di disk terdeteksi dan dimigrasikan ke layout saat ini.
  • Yang harus dilakukan: tidak ada, kecuali jika output yang sama juga menyertakan peringatan.
Matrix migration snapshot created before applying Matrix upgrades.
  • Arti: OpenClaw membuat arsip pemulihan sebelum memutasi state Matrix.
  • Yang harus dilakukan: simpan path arsip yang dicetak sampai Anda mengonfirmasi migrasi berhasil.
Matrix migration snapshot reused before applying Matrix upgrades.
  • Arti: OpenClaw menemukan marker snapshot migrasi Matrix yang sudah ada dan menggunakan kembali arsip tersebut alih-alih membuat backup duplikat.
  • Yang harus dilakukan: simpan path arsip yang dicetak sampai Anda mengonfirmasi migrasi berhasil.
Legacy Matrix state detected at ... but channels.matrix is not configured yet.
  • Arti: state Matrix lama ada, tetapi OpenClaw belum dapat memetakannya ke akun Matrix saat ini karena Matrix belum dikonfigurasi.
  • Yang harus dilakukan: konfigurasikan channels.matrix, lalu jalankan ulang openclaw doctor --fix atau restart 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...).
  • Arti: OpenClaw menemukan state lama, tetapi masih belum dapat menentukan root akun/perangkat saat ini secara tepat.
  • Yang harus dilakukan: jalankan gateway sekali dengan login Matrix yang berfungsi, atau jalankan ulang openclaw doctor --fix setelah kredensial cache tersedia.
Legacy Matrix state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.
  • Arti: OpenClaw menemukan satu store Matrix flat bersama, tetapi menolak menebak akun Matrix bernama mana yang seharusnya menerimanya.
  • Yang harus dilakukan: setel channels.matrix.defaultAccount ke akun yang dimaksud, lalu jalankan ulang openclaw doctor --fix atau restart gateway.
Matrix legacy sync store not migrated because the target already exists (...)
  • Arti: lokasi baru yang dicakup per akun sudah memiliki sync atau crypto store, sehingga OpenClaw tidak menimpanya secara otomatis.
  • Yang harus dilakukan: verifikasi bahwa akun saat ini memang akun yang benar sebelum menghapus atau memindahkan target yang konflik secara manual.
Failed migrating Matrix legacy sync store (...) atau Failed migrating Matrix legacy crypto store (...)
  • Arti: OpenClaw mencoba memindahkan state Matrix lama tetapi operasi filesystem gagal.
  • Yang harus dilakukan: periksa izin filesystem dan kondisi disk, lalu jalankan ulang openclaw doctor --fix.
Legacy Matrix encrypted state detected at ... but channels.matrix is not configured yet.
  • Arti: OpenClaw menemukan store Matrix terenkripsi lama, tetapi belum ada konfigurasi Matrix saat ini untuk menautkannya.
  • Yang harus dilakukan: konfigurasikan channels.matrix, lalu jalankan ulang openclaw doctor --fix atau restart 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...).
  • Arti: store terenkripsi ada, tetapi OpenClaw belum dapat memutuskan dengan aman akun/perangkat saat ini mana yang memilikinya.
  • Yang harus dilakukan: jalankan gateway sekali dengan login Matrix yang berfungsi, atau jalankan ulang openclaw doctor --fix setelah kredensial cache tersedia.
Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.
  • Arti: OpenClaw menemukan satu legacy crypto store flat bersama, tetapi menolak menebak akun Matrix bernama mana yang seharusnya menerimanya.
  • Yang harus dilakukan: setel channels.matrix.defaultAccount ke akun yang dimaksud, lalu jalankan ulang openclaw doctor --fix atau restart gateway.
Matrix migration warnings are present, but no on-disk Matrix mutation is actionable yet. No pre-migration snapshot was needed.
  • Arti: OpenClaw mendeteksi state Matrix lama, tetapi migrasi masih terblokir oleh data identitas atau kredensial yang belum ada.
  • Yang harus dilakukan: selesaikan login Matrix atau setup konfigurasi, lalu jalankan ulang openclaw doctor --fix atau restart 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.
  • Arti: OpenClaw menemukan state Matrix terenkripsi lama, tetapi tidak dapat memuat helper entrypoint dari plugin Matrix yang biasanya memeriksa store tersebut.
  • Yang harus dilakukan: instal ulang atau perbaiki plugin Matrix (openclaw plugins install @openclaw/matrix, atau openclaw plugins install ./path/to/local/matrix-plugin untuk checkout repo), lalu jalankan ulang openclaw doctor --fix atau restart gateway.
Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.
  • Arti: OpenClaw menemukan path file helper yang keluar dari root plugin atau gagal dalam pemeriksaan boundary plugin, sehingga OpenClaw menolak mengimpornya.
  • Yang harus dilakukan: instal ulang plugin Matrix dari path tepercaya, lalu jalankan ulang openclaw doctor --fix atau restart gateway.
- Failed creating a Matrix migration snapshot before repair: ... - Skipping Matrix migration changes for now. Resolve the snapshot failure, then rerun "openclaw doctor --fix".
  • Arti: OpenClaw menolak memutasi state Matrix karena tidak dapat membuat snapshot pemulihan terlebih dahulu.
  • Yang harus dilakukan: selesaikan error backup, lalu jalankan ulang openclaw doctor --fix atau restart gateway.
Failed migrating legacy Matrix client storage: ...
  • Arti: fallback sisi klien Matrix menemukan penyimpanan flat lama, tetapi pemindahannya gagal. OpenClaw kini membatalkan fallback tersebut alih-alih diam-diam memulai dengan store baru.
  • Yang harus dilakukan: periksa izin filesystem atau konflik, pertahankan state lama tetap utuh, dan coba lagi setelah memperbaiki error.
Matrix is installed from a custom path: ...
  • Arti: Matrix dipin ke instalasi path, sehingga pembaruan mainline tidak otomatis menggantinya dengan package Matrix standar repo.
  • Yang harus dilakukan: instal ulang dengan openclaw plugins install @openclaw/matrix saat Anda ingin kembali ke plugin Matrix default.

​
Pesan pemulihan state terenkripsi

matrix: restored X/Y room key(s) from legacy encrypted-state backup
  • Arti: room key yang dicadangkan berhasil dipulihkan ke crypto store baru.
  • Yang harus dilakukan: biasanya tidak ada.
matrix: N legacy local-only room key(s) were never backed up and could not be restored automatically
  • Arti: beberapa room key lama hanya ada di store lokal lama dan belum pernah diunggah ke backup Matrix.
  • Yang harus dilakukan: perkirakan beberapa riwayat terenkripsi lama tetap tidak tersedia kecuali Anda dapat memulihkan key tersebut secara manual dari klien lain yang terverifikasi.
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 <key>" after upgrade if they have the recovery key.
  • Arti: backup ada, tetapi OpenClaw tidak dapat memulihkan recovery key secara otomatis.
  • Yang harus dilakukan: jalankan openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".
Failed inspecting legacy Matrix encrypted state for account "..." (...): ...
  • Arti: OpenClaw menemukan store terenkripsi lama, tetapi tidak dapat memeriksanya dengan cukup aman untuk menyiapkan pemulihan.
  • Yang harus dilakukan: jalankan ulang openclaw doctor --fix. Jika terulang, pertahankan direktori state lama tetap utuh dan lakukan pemulihan menggunakan klien Matrix lain yang terverifikasi plus openclaw matrix verify backup restore --recovery-key "<your-recovery-key>".
Legacy Matrix backup key was found for account "...", but .../recovery-key.json already contains a different recovery key. Leaving the existing file unchanged.
  • Arti: OpenClaw mendeteksi konflik backup key dan menolak menimpa file recovery-key saat ini secara otomatis.
  • Yang harus dilakukan: verifikasi recovery key mana yang benar sebelum mencoba ulang command restore apa pun.
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.
  • Arti: ini adalah batas keras dari format penyimpanan lama.
  • Yang harus dilakukan: key yang dicadangkan masih dapat dipulihkan, tetapi riwayat terenkripsi khusus lokal mungkin tetap tidak tersedia.
matrix: failed restoring room keys from legacy encrypted-state backup: ...
  • Arti: plugin baru mencoba melakukan restore tetapi Matrix mengembalikan error.
  • Yang harus dilakukan: jalankan openclaw matrix verify backup status, lalu coba lagi dengan openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" jika diperlukan.

​
Pesan pemulihan manual

Backup key is not loaded on this device. Run 'openclaw matrix verify backup restore' to load it and restore old room keys.
  • Arti: OpenClaw tahu Anda seharusnya memiliki backup key, tetapi key tersebut tidak aktif pada perangkat ini.
  • Yang harus dilakukan: jalankan openclaw matrix verify backup restore, atau berikan --recovery-key jika diperlukan.
Store a recovery key with 'openclaw matrix verify device <key>', then run 'openclaw matrix verify backup restore'.
  • Arti: perangkat ini saat ini belum menyimpan recovery key.
  • Yang harus dilakukan: verifikasi perangkat dengan recovery key Anda terlebih dahulu, lalu restore backup.
Backup key mismatch on this device. Re-run 'openclaw matrix verify device <key>' with the matching recovery key.
  • Arti: key yang disimpan tidak cocok dengan backup Matrix aktif.
  • Yang harus dilakukan: jalankan ulang openclaw matrix verify device "<your-recovery-key>" dengan key yang benar.
Jika Anda menerima kehilangan riwayat terenkripsi lama yang tidak dapat dipulihkan, Anda dapat mereset baseline backup saat ini dengan openclaw matrix verify backup reset --yes. Saat secret backup yang tersimpan rusak, reset tersebut juga dapat membuat ulang secret storage sehingga backup key baru dapat dimuat dengan benar setelah restart. Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device <key>'.
  • Arti: backup ada, tetapi perangkat ini belum cukup kuat mempercayai rantai cross-signing.
  • Yang harus dilakukan: jalankan ulang openclaw matrix verify device "<your-recovery-key>".
Matrix recovery key is required
  • Arti: Anda mencoba langkah pemulihan tanpa memberikan recovery key saat key itu diwajibkan.
  • Yang harus dilakukan: jalankan ulang command dengan recovery key Anda.
Invalid Matrix recovery key: ...
  • Arti: key yang diberikan tidak dapat diparse atau tidak cocok dengan format yang diharapkan.
  • Yang harus dilakukan: coba lagi dengan recovery key persis dari klien Matrix atau file recovery-key Anda.
Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.
  • Arti: key telah diterapkan, tetapi perangkat masih belum dapat menyelesaikan verifikasi.
  • Yang harus dilakukan: pastikan Anda menggunakan key yang benar dan cross-signing tersedia pada akun, lalu coba lagi.
Matrix key backup is not active on this device after loading from secret storage.
  • Arti: secret storage tidak menghasilkan sesi backup aktif pada perangkat ini.
  • Yang harus dilakukan: verifikasi perangkat terlebih dahulu, lalu periksa lagi dengan openclaw matrix verify backup status.
Matrix crypto backend cannot load backup keys from secret storage. Verify this device with 'openclaw matrix verify device <key>' first.
  • Arti: perangkat ini tidak dapat memulihkan dari secret storage sampai verifikasi perangkat selesai.
  • Yang harus dilakukan: jalankan openclaw matrix verify device "<your-recovery-key>" terlebih dahulu.

​
Pesan instalasi plugin kustom

Matrix is installed from a custom path that no longer exists: ...
  • Arti: rekaman instalasi plugin Anda menunjuk ke path lokal yang sudah tidak ada.
  • Yang harus dilakukan: instal ulang dengan openclaw plugins install @openclaw/matrix, atau jika Anda menjalankan dari checkout repo, openclaw plugins install ./path/to/local/matrix-plugin.

​
Jika riwayat terenkripsi masih belum kembali

Jalankan pemeriksaan ini secara berurutan: 
openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose
Jika backup berhasil dipulihkan tetapi beberapa room lama masih kehilangan riwayat, kemungkinan key yang hilang tersebut tidak pernah dicadangkan oleh plugin sebelumnya.

​
Jika Anda ingin memulai baru untuk pesan mendatang

Jika Anda menerima kehilangan riwayat terenkripsi lama yang tidak dapat dipulihkan dan hanya menginginkan baseline backup yang bersih ke depannya, jalankan command ini secara berurutan: 
openclaw matrix verify backup reset --yes
openclaw matrix verify backup status --verbose
openclaw matrix verify status
Jika setelah itu perangkat masih belum terverifikasi, selesaikan verifikasi dari klien Matrix Anda dengan membandingkan emoji SAS atau kode desimal dan mengonfirmasi bahwa keduanya cocok.

​
Halaman terkait