Migrasi Matrix

• Plugin tetap @openclaw/matrix
• channel tetap matrix
• konfigurasi Anda tetap berada di bawah channels.matrix
• kredensial yang di-cache tetap berada di bawah ~/.openclaw/credentials/matrix/
• status runtime tetap berada di bawah ~/.openclaw/matrix/

​

Yang dilakukan migrasi secara otomatis

• instalasi sumber menjalankan openclaw doctor --fix selama alur pembaruan, lalu memulai ulang Gateway secara default
• instalasi pengelola paket memperbarui paket, menjalankan pemeriksaan doctor non-interaktif, lalu mengandalkan restart Gateway default agar startup dapat menyelesaikan migrasi Matrix
• jika Anda menggunakan openclaw update --no-restart, migrasi Matrix yang didukung startup ditunda hingga nanti Anda menjalankan openclaw doctor --fix dan memulai ulang Gateway

• membuat atau menggunakan kembali snapshot pra-migrasi di bawah ~/Backups/openclaw-migrations/
• menggunakan kembali kredensial Matrix yang di-cache
• mempertahankan pemilihan akun yang sama dan konfigurasi channels.matrix
• memindahkan penyimpanan sinkronisasi Matrix datar tertua ke lokasi saat ini yang berlingkup akun
• memindahkan penyimpanan crypto Matrix datar tertua ke lokasi saat ini yang berlingkup akun saat akun target dapat diselesaikan dengan aman
• mengekstrak kunci dekripsi cadangan kunci ruang Matrix yang sebelumnya disimpan dari penyimpanan rust crypto lama, saat kunci tersebut tersedia secara lokal
• menggunakan kembali root penyimpanan hash-token paling lengkap yang sudah ada untuk akun Matrix, homeserver, dan pengguna yang sama saat token akses berubah nanti
• memindai root penyimpanan hash-token saudara untuk metadata pemulihan status terenkripsi yang tertunda saat token akses Matrix berubah tetapi identitas akun/perangkat tetap sama
• memulihkan kunci ruang yang dicadangkan ke penyimpanan crypto baru pada startup Matrix berikutnya

• OpenClaw menulis file penanda di ~/.openclaw/matrix/migration-snapshot.json setelah snapshot berhasil sehingga startup dan pemeriksaan perbaikan berikutnya dapat menggunakan kembali arsip yang sama.
• Snapshot migrasi Matrix otomatis ini hanya mencadangkan konfigurasi + status (includeWorkspace: false).
• Jika Matrix hanya memiliki status migrasi peringatan saja, misalnya karena userId atau accessToken masih hilang, OpenClaw belum membuat snapshot karena belum ada mutasi Matrix yang dapat ditindaklanjuti.
• Jika langkah snapshot gagal, OpenClaw melewati migrasi Matrix untuk proses tersebut alih-alih mengubah status tanpa titik pemulihan.

• penyimpanan Matrix datar tertua (~/.openclaw/matrix/bot-storage.json dan ~/.openclaw/matrix/crypto/) berasal dari tata letak penyimpanan tunggal, sehingga OpenClaw hanya dapat memigrasikannya ke satu target akun Matrix yang terselesaikan
• penyimpanan Matrix lama yang sudah berlingkup akun dideteksi dan disiapkan per akun Matrix yang dikonfigurasi

​

Yang tidak dapat dilakukan migrasi secara otomatis

• kunci ruang lokal saja yang tidak pernah dicadangkan
• status terenkripsi saat akun Matrix target belum dapat diselesaikan karena homeserver, userId, atau accessToken masih belum tersedia
• migrasi otomatis satu penyimpanan Matrix datar bersama saat beberapa akun Matrix dikonfigurasi tetapi channels.matrix.defaultAccount tidak diatur
• instalasi jalur Plugin kustom yang dipatok ke jalur repo alih-alih paket Matrix standar
• kunci pemulihan yang hilang saat penyimpanan lama memiliki kunci yang dicadangkan tetapi tidak menyimpan kunci dekripsi secara lokal

• instalasi jalur Plugin Matrix kustom ditampilkan oleh startup Gateway dan openclaw doctor

​

Alur peningkatan yang direkomendasikan

1. Perbarui OpenClaw dan Plugin Matrix seperti biasa. Sebaiknya gunakan openclaw update biasa tanpa --no-restart agar startup dapat segera 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 jalur arsip.
3. Mulai atau mulai ulang Gateway.
4. Periksa status verifikasi dan cadangan saat ini:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Letakkan kunci pemulihan untuk akun Matrix yang Anda perbaiki dalam variabel lingkungan khusus akun. Untuk satu akun default, MATRIX_RECOVERY_KEY sudah cukup. Untuk beberapa akun, gunakan satu variabel per akun, misalnya MATRIX_RECOVERY_KEY_ASSISTANT, dan tambahkan --account assistant ke perintah.
6. Jika OpenClaw memberi tahu Anda bahwa kunci pemulihan diperlukan, jalankan perintah untuk akun yang sesuai:
   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. Jika perangkat ini masih belum diverifikasi, jalankan perintah untuk akun yang sesuai:
   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
   
   Jika kunci pemulihan diterima dan cadangan dapat digunakan, tetapi Cross-signing verified masih no, selesaikan verifikasi mandiri dari klien Matrix lain:
   openclaw matrix verify self
   
   Terima permintaan di klien Matrix lain, bandingkan emoji atau desimal, dan ketik yes hanya saat semuanya cocok. Perintah berhasil keluar hanya setelah Cross-signing verified menjadi yes.
8. Jika Anda sengaja meninggalkan riwayat lama yang tidak dapat dipulihkan dan menginginkan baseline cadangan baru untuk pesan mendatang, jalankan:
   openclaw matrix verify backup reset --yes
   
9. Jika belum ada cadangan kunci sisi server, buat satu untuk pemulihan di masa mendatang:
   openclaw matrix verify bootstrap
   

​

Cara kerja migrasi terenkripsi

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 penyimpanan crypto Matrix lama melalui instalasi Plugin Matrix aktif.
3. Jika kunci dekripsi cadangan ditemukan, OpenClaw menulisnya ke alur kunci pemulihan baru dan menandai pemulihan kunci ruang sebagai tertunda.
4. Pada startup Matrix berikutnya, OpenClaw memulihkan kunci ruang yang dicadangkan ke penyimpanan crypto baru secara otomatis.

​

Pesan umum dan artinya

​

Pesan peningkatan dan deteksi

• Arti: status Matrix lama di disk terdeteksi dan dimigrasikan ke tata letak saat ini.
• Yang harus dilakukan: tidak ada kecuali output yang sama juga menyertakan peringatan.

• Arti: OpenClaw membuat arsip pemulihan sebelum mengubah status Matrix.
• Yang harus dilakukan: simpan jalur arsip yang dicetak hingga Anda memastikan migrasi berhasil.

• Arti: OpenClaw menemukan penanda snapshot migrasi Matrix yang sudah ada dan menggunakan kembali arsip tersebut alih-alih membuat cadangan duplikat.
• Yang harus dilakukan: simpan jalur arsip yang dicetak hingga Anda memastikan migrasi berhasil.

• Arti: status Matrix lama ada, tetapi OpenClaw tidak dapat memetakannya ke akun Matrix saat ini karena Matrix belum dikonfigurasi.
• Yang harus dilakukan: konfigurasikan channels.matrix, lalu jalankan ulang openclaw doctor --fix atau mulai ulang Gateway.

• Arti: OpenClaw menemukan status lama, tetapi masih belum dapat menentukan root akun/perangkat saat ini yang tepat.
• Yang harus dilakukan: mulai Gateway sekali dengan login Matrix yang berfungsi, atau jalankan ulang openclaw doctor --fix setelah kredensial yang di-cache tersedia.

• Arti: OpenClaw menemukan satu penyimpanan Matrix datar bersama, tetapi menolak menebak akun Matrix bernama mana yang harus menerimanya.
• Yang harus dilakukan: atur channels.matrix.defaultAccount ke akun yang dimaksud, lalu jalankan ulang openclaw doctor --fix atau mulai ulang Gateway.

• Arti: lokasi baru yang berlingkup akun sudah memiliki penyimpanan sinkronisasi atau crypto, sehingga OpenClaw tidak menimpanya secara otomatis.
• Yang harus dilakukan: verifikasi bahwa akun saat ini adalah akun yang benar sebelum menghapus atau memindahkan target yang bertentangan secara manual.

• Arti: OpenClaw mencoba memindahkan status Matrix lama tetapi operasi sistem file gagal.
• Yang harus dilakukan: periksa izin sistem file dan status disk, lalu jalankan ulang openclaw doctor --fix.

• Arti: OpenClaw menemukan penyimpanan Matrix terenkripsi lama, tetapi tidak ada konfigurasi Matrix saat ini untuk melampirkannya.
• Yang harus dilakukan: konfigurasikan channels.matrix, lalu jalankan ulang openclaw doctor --fix atau mulai ulang Gateway.

• Arti: penyimpanan terenkripsi ada, tetapi OpenClaw tidak dapat dengan aman memutuskan akun/perangkat saat ini mana yang memilikinya.
• Yang harus dilakukan: mulai Gateway sekali dengan login Matrix yang berfungsi, atau jalankan ulang openclaw doctor --fix setelah kredensial yang di-cache tersedia.

• Arti: OpenClaw menemukan satu penyimpanan crypto lama datar bersama, tetapi menolak menebak akun Matrix bernama mana yang harus menerimanya.
• Yang harus dilakukan: atur channels.matrix.defaultAccount ke akun yang dimaksud, lalu jalankan ulang openclaw doctor --fix atau mulai ulang Gateway.

• Arti: OpenClaw mendeteksi status Matrix lama, tetapi migrasi masih terblokir oleh data identitas atau kredensial yang hilang.
• Yang harus dilakukan: selesaikan login Matrix atau penyiapan konfigurasi, lalu jalankan ulang openclaw doctor --fix atau mulai ulang Gateway.

• Arti: OpenClaw menemukan state Matrix terenkripsi lama, tetapi tidak dapat memuat entrypoint pembantu 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 mulai ulang gateway.

• Arti: OpenClaw menemukan jalur file pembantu yang keluar dari root plugin atau gagal melewati pemeriksaan batas plugin, sehingga OpenClaw menolak mengimpornya.
• Yang harus dilakukan: instal ulang Plugin Matrix dari jalur tepercaya, lalu jalankan ulang openclaw doctor --fix atau mulai ulang gateway.

• Arti: OpenClaw menolak mengubah state Matrix karena tidak dapat membuat snapshot pemulihan terlebih dahulu.
• Yang harus dilakukan: selesaikan kesalahan pencadangan, lalu jalankan ulang openclaw doctor --fix atau mulai ulang gateway.

• Arti: fallback sisi klien Matrix menemukan penyimpanan datar lama, tetapi pemindahannya gagal. OpenClaw sekarang membatalkan fallback tersebut alih-alih diam-diam memulai dengan store baru.
• Yang harus dilakukan: periksa izin atau konflik sistem file, pertahankan state lama tetap utuh, dan coba lagi setelah memperbaiki kesalahan.

• Arti: Matrix dipasang dengan path install tertentu, sehingga pembaruan mainline tidak otomatis menggantinya dengan paket Matrix standar dari repo.
• Yang harus dilakukan: instal ulang dengan openclaw plugins install @openclaw/matrix saat Anda ingin kembali ke Plugin Matrix default.

​

Pesan pemulihan state terenkripsi

• Arti: kunci ruang yang dicadangkan berhasil dipulihkan ke crypto store baru.
• Yang harus dilakukan: biasanya tidak ada.

• Arti: beberapa kunci ruang lama hanya ada di store lokal lama dan belum pernah diunggah ke cadangan Matrix.
• Yang harus dilakukan: perkirakan sebagian riwayat terenkripsi lama tetap tidak tersedia kecuali Anda dapat memulihkan kunci tersebut secara manual dari klien terverifikasi lain.

• Arti: cadangan ada, tetapi OpenClaw tidak dapat memulihkan kunci pemulihan secara otomatis.
• Yang harus dilakukan: jalankan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• 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 berulang, pertahankan direktori state lama tetap utuh dan pulihkan menggunakan klien Matrix terverifikasi lain ditambah printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Arti: OpenClaw mendeteksi konflik kunci cadangan dan menolak menimpa file recovery-key saat ini secara otomatis.
• Yang harus dilakukan: verifikasi kunci pemulihan mana yang benar sebelum mencoba lagi perintah pemulihan apa pun.

• Arti: ini adalah batas keras format penyimpanan lama.
• Yang harus dilakukan: kunci yang dicadangkan masih dapat dipulihkan, tetapi riwayat terenkripsi yang hanya ada secara lokal mungkin tetap tidak tersedia.

• Arti: plugin baru mencoba pemulihan, tetapi Matrix mengembalikan kesalahan.
• Yang harus dilakukan: jalankan openclaw matrix verify backup status, lalu coba lagi dengan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin jika perlu.

​

Pesan pemulihan manual

• Arti: OpenClaw tahu Anda seharusnya memiliki kunci cadangan, tetapi kunci tersebut tidak aktif di perangkat ini.
• Yang harus dilakukan: jalankan openclaw matrix verify backup restore, atau atur MATRIX_RECOVERY_KEY dan jalankan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin jika perlu.

• Arti: perangkat ini saat ini belum menyimpan kunci pemulihan.
• Yang harus dilakukan: atur MATRIX_RECOVERY_KEY, jalankan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin, lalu pulihkan cadangan.

• Arti: kunci yang tersimpan tidak cocok dengan cadangan Matrix aktif.
• Yang harus dilakukan: atur MATRIX_RECOVERY_KEY ke kunci yang benar dan jalankan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Arti: cadangan ada, tetapi perangkat ini belum cukup memercayai rantai cross-signing.
• Yang harus dilakukan: atur MATRIX_RECOVERY_KEY dan jalankan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Arti: Anda mencoba langkah pemulihan tanpa menyediakan kunci pemulihan saat kunci tersebut diperlukan.
• Yang harus dilakukan: jalankan ulang perintah dengan --recovery-key-stdin, misalnya printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Arti: kunci yang diberikan tidak dapat diurai atau tidak cocok dengan format yang diharapkan.
• Yang harus dilakukan: coba lagi dengan kunci pemulihan persis dari klien Matrix atau file recovery-key Anda.

• Arti: OpenClaw dapat menerapkan kunci pemulihan, tetapi Matrix masih belum menetapkan kepercayaan identitas cross-signing penuh untuk perangkat ini. Periksa output perintah untuk Recovery key accepted, Backup usable, Cross-signing verified, dan Device verified by owner.
• Yang harus dilakukan: jalankan openclaw matrix verify self, terima permintaan di klien Matrix lain, bandingkan SAS, dan ketik yes hanya saat cocok. Perintah menunggu kepercayaan identitas Matrix penuh sebelum melaporkan sukses. Gunakan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing hanya saat Anda sengaja ingin mengganti identitas cross-signing saat ini.

• Arti: secret storage tidak menghasilkan sesi cadangan aktif di perangkat ini.
• Yang harus dilakukan: verifikasi perangkat terlebih dahulu, lalu periksa ulang dengan openclaw matrix verify backup status.

• Arti: perangkat ini tidak dapat memulihkan dari secret storage sampai verifikasi perangkat selesai.
• Yang harus dilakukan: jalankan printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin terlebih dahulu.

​

Pesan instal plugin kustom

• Arti: catatan instal plugin Anda menunjuk ke jalur 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

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

​

Jika Anda ingin memulai baru untuk pesan mendatang

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

​

Terkait

• Matrix: penyiapan dan konfigurasi channel.
• Aturan push Matrix: perutean notifikasi.
• Doctor: pemeriksaan kesehatan dan pemicu migrasi otomatis.
• Panduan migrasi: semua jalur migrasi (pemindahan mesin, impor lintas sistem).
• Plugin: instalasi dan pendaftaran plugin.