Migracja Matrixa

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• plugin pozostaje @openclaw/matrix
• kanał pozostaje matrix
• konfiguracja pozostaje pod channels.matrix
• dane uwierzytelniające w pamięci podręcznej pozostają pod ~/.openclaw/credentials/matrix/
• stan runtime pozostaje pod ~/.openclaw/matrix/

​

Co migracja wykonuje automatycznie

• instalacje ze źródeł uruchamiają openclaw doctor --fix podczas przepływu aktualizacji, a następnie domyślnie restartują Gateway
• instalacje przez menedżera pakietów aktualizują pakiet, uruchamiają nieinteraktywny przebieg doctor, a następnie polegają na domyślnym restarcie Gateway, aby uruchamianie mogło dokończyć migrację Matrix
• jeśli używasz openclaw update --no-restart, migracja Matrix wsparta uruchamianiem zostaje odroczona do czasu, gdy później uruchomisz openclaw doctor --fix i zrestartujesz Gateway

• tworzenie lub ponowne wykorzystanie migawki sprzed migracji pod ~/Backups/openclaw-migrations/
• ponowne użycie danych uwierzytelniających Matrix z pamięci podręcznej
• zachowanie tego samego wyboru konta i konfiguracji channels.matrix
• przeniesienie najstarszego płaskiego magazynu synchronizacji Matrix do bieżącej lokalizacji powiązanej z kontem
• przeniesienie najstarszego płaskiego magazynu kryptograficznego Matrix do bieżącej lokalizacji powiązanej z kontem, gdy konto docelowe można bezpiecznie rozwiązać
• wyodrębnienie wcześniej zapisanego klucza deszyfrowania kopii zapasowej kluczy pokojów Matrix ze starego magazynu kryptograficznego rust, gdy taki klucz istnieje lokalnie
• ponowne wykorzystanie najbardziej kompletnego istniejącego katalogu głównego magazynu z hashem tokenu dla tego samego konta Matrix, homeservera i użytkownika, gdy token dostępu zmieni się później
• skanowanie sąsiednich katalogów głównych magazynu z hashem tokenu w poszukiwaniu oczekujących metadanych przywracania zaszyfrowanego stanu, gdy token dostępu Matrix się zmienił, ale tożsamość konta/urządzenia pozostała taka sama
• przywrócenie kluczy pokojów z kopii zapasowej do nowego magazynu kryptograficznego przy następnym uruchomieniu Matrix

• OpenClaw zapisuje plik znacznika w ~/.openclaw/matrix/migration-snapshot.json po udanej migawce, aby późniejsze przebiegi uruchamiania i naprawy mogły ponownie wykorzystać to samo archiwum.
• Te automatyczne migawki migracji Matrix tworzą kopię zapasową tylko konfiguracji i stanu (includeWorkspace: false).
• Jeśli Matrix ma tylko stan migracji wyłącznie z ostrzeżeniami, na przykład dlatego, że nadal brakuje userId lub accessToken, OpenClaw nie tworzy jeszcze migawki, ponieważ żadna mutacja Matrix nie jest wykonywalna.
• Jeśli krok migawki się nie powiedzie, OpenClaw pomija migrację Matrix w tym przebiegu zamiast zmieniać stan bez punktu odzyskiwania.

• najstarszy płaski magazyn Matrix (~/.openclaw/matrix/bot-storage.json i ~/.openclaw/matrix/crypto/) pochodził z układu z jednym magazynem, więc OpenClaw może zmigrować go tylko do jednego rozwiązanego celu konta Matrix
• już powiązane z kontem starsze magazyny Matrix są wykrywane i przygotowywane osobno dla każdego skonfigurowanego konta Matrix

​

Czego migracja nie może zrobić automatycznie

• wyłącznie lokalnych kluczy pokojów, których nigdy nie zapisano w kopii zapasowej
• zaszyfrowanego stanu, gdy docelowego konta Matrix nie można jeszcze rozwiązać, ponieważ homeserver, userId lub accessToken są nadal niedostępne
• automatycznej migracji jednego współdzielonego płaskiego magazynu Matrix, gdy skonfigurowano wiele kont Matrix, ale channels.matrix.defaultAccount nie jest ustawione
• instalacji z niestandardową ścieżką pluginu przypiętych do ścieżki repozytorium zamiast standardowego pakietu Matrix
• brakującego klucza odzyskiwania, gdy stary magazyn miał klucze w kopii zapasowej, ale nie zachował klucza deszyfrowania lokalnie

• instalacje z niestandardową ścieżką pluginu Matrix są zgłaszane zarówno przez uruchamianie Gateway, jak i openclaw doctor

​

Zalecany przepływ aktualizacji

1. Zaktualizuj OpenClaw i Plugin Matrix w zwykły sposób. Preferuj zwykłe openclaw update bez --no-restart, aby uruchamianie mogło natychmiast dokończyć migrację Matrix.
2. Uruchom:
   openclaw doctor --fix
   
   Jeśli Matrix ma wykonywalną pracę migracyjną, doctor najpierw utworzy lub ponownie wykorzysta migawkę sprzed migracji i wypisze ścieżkę archiwum.
3. Uruchom lub zrestartuj Gateway.
4. Sprawdź bieżący stan weryfikacji i kopii zapasowej:
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. Umieść klucz odzyskiwania dla konta Matrix, które naprawiasz, w zmiennej środowiskowej specyficznej dla konta. Dla jednego konta domyślnego MATRIX_RECOVERY_KEY jest w porządku. Dla wielu kont użyj jednej zmiennej na konto, na przykład MATRIX_RECOVERY_KEY_ASSISTANT, i dodaj --account assistant do polecenia.
6. Jeśli OpenClaw poinformuje, że potrzebny jest klucz odzyskiwania, uruchom polecenie dla pasującego konta:
   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. Jeśli to urządzenie nadal nie jest zweryfikowane, uruchom polecenie dla pasującego konta:
   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
   
   Jeśli klucz odzyskiwania zostanie zaakceptowany, a kopia zapasowa jest użyteczna, ale Cross-signing verified nadal ma wartość no, dokończ samoweryfikację z innego klienta Matrix:
   openclaw matrix verify self
   
   Zaakceptuj żądanie w innym kliencie Matrix, porównaj emoji lub liczby dziesiętne i wpisz yes tylko wtedy, gdy się zgadzają. Polecenie kończy się pomyślnie dopiero po tym, jak Cross-signing verified stanie się yes.
8. Jeśli celowo porzucasz nieodzyskiwalną starą historię i chcesz świeżej bazowej kopii zapasowej dla przyszłych wiadomości, uruchom:
   openclaw matrix verify backup reset --yes
   
9. Jeśli kopia zapasowa kluczy po stronie serwera jeszcze nie istnieje, utwórz ją dla przyszłego odzyskiwania:
   openclaw matrix verify bootstrap
   

​

Jak działa migracja szyfrowana

1. Uruchamianie lub openclaw doctor --fix tworzy albo ponownie wykorzystuje migawkę sprzed migracji, jeśli migracja szyfrowana jest wykonywalna.
2. Uruchamianie lub openclaw doctor --fix sprawdza stary magazyn kryptograficzny Matrix przez aktywną instalację pluginu Matrix.
3. Jeśli klucz deszyfrowania kopii zapasowej zostanie znaleziony, OpenClaw zapisuje go w nowym przepływie klucza odzyskiwania i oznacza przywracanie kluczy pokojów jako oczekujące.
4. Przy następnym uruchomieniu Matrix OpenClaw automatycznie przywraca klucze pokojów z kopii zapasowej do nowego magazynu kryptograficznego.

​

Typowe komunikaty i ich znaczenie

​

Komunikaty aktualizacji i wykrywania

• Znaczenie: stary stan Matrix na dysku został wykryty i zmigrowany do bieżącego układu.
• Co zrobić: nic, chyba że ten sam wynik zawiera również ostrzeżenia.

• Znaczenie: OpenClaw utworzył archiwum odzyskiwania przed zmianą stanu Matrix.
• Co zrobić: zachowaj wypisaną ścieżkę archiwum, dopóki nie potwierdzisz, że migracja się powiodła.

• Znaczenie: OpenClaw znalazł istniejący znacznik migawki migracji Matrix i ponownie wykorzystał to archiwum zamiast tworzyć zduplikowaną kopię zapasową.
• Co zrobić: zachowaj wypisaną ścieżkę archiwum, dopóki nie potwierdzisz, że migracja się powiodła.

• Znaczenie: istnieje stary stan Matrix, ale OpenClaw nie może zmapować go na bieżące konto Matrix, ponieważ Matrix nie jest skonfigurowany.
• Co zrobić: skonfiguruj channels.matrix, a następnie ponownie uruchom openclaw doctor --fix lub zrestartuj Gateway.

• Znaczenie: OpenClaw znalazł stary stan, ale nadal nie może ustalić dokładnego bieżącego katalogu głównego konta/urządzenia.
• Co zrobić: uruchom Gateway raz z działającym logowaniem Matrix albo ponownie uruchom openclaw doctor --fix po tym, jak dane uwierzytelniające w pamięci podręcznej będą istnieć.

• Znaczenie: OpenClaw znalazł jeden współdzielony płaski magazyn Matrix, ale odmawia zgadywania, które nazwane konto Matrix powinno go otrzymać.
• Co zrobić: ustaw channels.matrix.defaultAccount na zamierzone konto, a następnie ponownie uruchom openclaw doctor --fix lub zrestartuj Gateway.

• Znaczenie: nowa lokalizacja powiązana z kontem ma już magazyn synchronizacji lub kryptograficzny, więc OpenClaw nie nadpisał jej automatycznie.
• Co zrobić: sprawdź, czy bieżące konto jest właściwe, zanim ręcznie usuniesz lub przeniesiesz kolidujący cel.

• Znaczenie: OpenClaw próbował przenieść stary stan Matrix, ale operacja systemu plików się nie powiodła.
• Co zrobić: sprawdź uprawnienia systemu plików i stan dysku, a następnie ponownie uruchom openclaw doctor --fix.

• Znaczenie: OpenClaw znalazł stary zaszyfrowany magazyn Matrix, ale nie ma bieżącej konfiguracji Matrix, do której można go dołączyć.
• Co zrobić: skonfiguruj channels.matrix, a następnie ponownie uruchom openclaw doctor --fix lub zrestartuj Gateway.

• Znaczenie: zaszyfrowany magazyn istnieje, ale OpenClaw nie może bezpiecznie zdecydować, do którego bieżącego konta/urządzenia należy.
• Co zrobić: uruchom Gateway raz z działającym logowaniem Matrix albo ponownie uruchom openclaw doctor --fix po udostępnieniu danych uwierzytelniających w pamięci podręcznej.

• Znaczenie: OpenClaw znalazł jeden współdzielony płaski starszy magazyn kryptograficzny, ale odmawia zgadywania, które nazwane konto Matrix powinno go otrzymać.
• Co zrobić: ustaw channels.matrix.defaultAccount na zamierzone konto, a następnie ponownie uruchom openclaw doctor --fix lub zrestartuj Gateway.

• Znaczenie: OpenClaw wykrył stary stan Matrix, ale migracja nadal jest zablokowana przez brakujące dane tożsamości lub dane uwierzytelniające.
• Co zrobić: dokończ logowanie Matrix lub konfigurację, a następnie ponownie uruchom openclaw doctor --fix lub zrestartuj Gateway.

• Znaczenie: OpenClaw znalazł stary zaszyfrowany stan Matrix, ale nie mógł wczytać pomocniczego punktu wejścia z Pluginu Matrix, który zwykle sprawdza ten magazyn.
• Co zrobić: zainstaluj ponownie lub napraw Plugin Matrix (openclaw plugins install @openclaw/matrix albo openclaw plugins install ./path/to/local/matrix-plugin dla kopii roboczej repozytorium), a następnie ponownie uruchom openclaw doctor --fix albo zrestartuj gateway.
• Jeśli npm zgłasza należący do OpenClaw pakiet Matrix jako przestarzały, użyj dołączonego Pluginu z bieżącej spakowanej kompilacji OpenClaw albo lokalnej ścieżki kopii roboczej, dopóki nie zostanie opublikowany nowszy pakiet npm.

• Znaczenie: OpenClaw znalazł ścieżkę pliku pomocniczego, która wychodzi poza katalog główny Pluginu albo nie przechodzi kontroli granic Pluginu, więc odmówił jej zaimportowania.
• Co zrobić: zainstaluj ponownie Plugin Matrix z zaufanej ścieżki, a następnie ponownie uruchom openclaw doctor --fix albo zrestartuj gateway.

• Znaczenie: OpenClaw odmówił modyfikacji stanu Matrix, ponieważ najpierw nie mógł utworzyć migawki odzyskiwania.
• Co zrobić: rozwiąż błąd kopii zapasowej, a następnie ponownie uruchom openclaw doctor --fix albo zrestartuj gateway.

• Znaczenie: awaryjny mechanizm po stronie klienta Matrix znalazł stary płaski magazyn, ale przenoszenie się nie powiodło. OpenClaw przerywa teraz ten awaryjny mechanizm zamiast po cichu uruchamiać się ze świeżym magazynem.
• Co zrobić: sprawdź uprawnienia systemu plików lub konflikty, zachowaj stary stan bez zmian i ponów próbę po naprawieniu błędu.

• Znaczenie: Matrix jest przypięty do instalacji ze ścieżki, więc główne aktualizacje nie zastąpią go automatycznie standardowym pakietem Matrix z repozytorium.
• Co zrobić: zainstaluj ponownie za pomocą openclaw plugins install @openclaw/matrix, gdy chcesz wrócić do domyślnego Pluginu Matrix.
• Jeśli npm zgłasza należący do OpenClaw pakiet Matrix jako przestarzały, użyj dołączonego Pluginu z bieżącej spakowanej kompilacji OpenClaw, dopóki nie zostanie opublikowany nowszy pakiet npm.

​

Komunikaty odzyskiwania zaszyfrowanego stanu

• Znaczenie: zapisane w kopii zapasowej klucze pokojów zostały pomyślnie przywrócone do nowego magazynu kryptograficznego.
• Co zrobić: zwykle nic.

• Znaczenie: część starych kluczy pokojów istniała tylko w starym magazynie lokalnym i nigdy nie została przesłana do kopii zapasowej Matrix.
• Co zrobić: spodziewaj się, że część starej zaszyfrowanej historii pozostanie niedostępna, chyba że możesz ręcznie odzyskać te klucze z innego zweryfikowanego klienta.

• Znaczenie: kopia zapasowa istnieje, ale OpenClaw nie mógł automatycznie odzyskać klucza odzyskiwania.
• Co zrobić: uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Znaczenie: OpenClaw znalazł stary zaszyfrowany magazyn, ale nie mógł sprawdzić go wystarczająco bezpiecznie, aby przygotować odzyskiwanie.
• Co zrobić: ponownie uruchom openclaw doctor --fix. Jeśli problem się powtórzy, zachowaj katalog starego stanu bez zmian i odzyskaj dane przy użyciu innego zweryfikowanego klienta Matrix oraz printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Znaczenie: OpenClaw wykrył konflikt klucza kopii zapasowej i odmówił automatycznego nadpisania bieżącego pliku recovery-key.
• Co zrobić: sprawdź, który klucz odzyskiwania jest poprawny, zanim ponowisz dowolne polecenie przywracania.

• Znaczenie: to twarde ograniczenie starego formatu magazynu.
• Co zrobić: klucze z kopii zapasowej nadal można przywrócić, ale lokalna zaszyfrowana historia może pozostać niedostępna.

• Znaczenie: nowy Plugin podjął próbę przywrócenia, ale Matrix zwrócił błąd.
• Co zrobić: uruchom openclaw matrix verify backup status, a następnie w razie potrzeby ponów próbę za pomocą printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

​

Komunikaty ręcznego odzyskiwania

• Znaczenie: OpenClaw wie, że powinien istnieć klucz kopii zapasowej, ale nie jest on aktywny na tym urządzeniu.
• Co zrobić: uruchom openclaw matrix verify backup restore albo ustaw MATRIX_RECOVERY_KEY i w razie potrzeby uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

• Znaczenie: to urządzenie nie ma obecnie zapisanego klucza odzyskiwania.
• Co zrobić: ustaw MATRIX_RECOVERY_KEY, uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin, a następnie przywróć kopię zapasową.

• Znaczenie: zapisany klucz nie pasuje do aktywnej kopii zapasowej Matrix.
• Co zrobić: ustaw MATRIX_RECOVERY_KEY na poprawny klucz i uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Znaczenie: kopia zapasowa istnieje, ale to urządzenie nie ufa jeszcze wystarczająco mocno łańcuchowi podpisywania krzyżowego.
• Co zrobić: ustaw MATRIX_RECOVERY_KEY i uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Znaczenie: próbowano wykonać krok odzyskiwania bez podania klucza odzyskiwania, gdy był on wymagany.
• Co zrobić: uruchom polecenie ponownie z --recovery-key-stdin, na przykład printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Znaczenie: podanego klucza nie można było sparsować albo nie pasował do oczekiwanego formatu.
• Co zrobić: ponów próbę z dokładnym kluczem odzyskiwania z klienta Matrix albo z pliku recovery-key.

• Znaczenie: OpenClaw mógł zastosować klucz odzyskiwania, ale Matrix nadal nie ustanowił pełnego zaufania tożsamości podpisywania krzyżowego dla tego urządzenia. Sprawdź wyjście polecenia pod kątem Recovery key accepted, Backup usable, Cross-signing verified i Device verified by owner.
• Co zrobić: uruchom openclaw matrix verify self, zaakceptuj żądanie w innym kliencie Matrix, porównaj SAS i wpisz yes tylko wtedy, gdy się zgadza. Polecenie czeka na pełne zaufanie tożsamości Matrix przed zgłoszeniem sukcesu. Użyj printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing tylko wtedy, gdy celowo chcesz zastąpić bieżącą tożsamość podpisywania krzyżowego.

• Znaczenie: magazyn sekretów nie utworzył aktywnej sesji kopii zapasowej na tym urządzeniu.
• Co zrobić: najpierw zweryfikuj urządzenie, a następnie sprawdź ponownie za pomocą openclaw matrix verify backup status.

• Znaczenie: to urządzenie nie może przywracać z magazynu sekretów, dopóki weryfikacja urządzenia nie zostanie ukończona.
• Co zrobić: najpierw uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

​

Komunikaty instalacji niestandardowego Pluginu

• Znaczenie: rekord instalacji Pluginu wskazuje na lokalną ścieżkę, która już nie istnieje.
• Co zrobić: zainstaluj ponownie za pomocą openclaw plugins install @openclaw/matrix, albo jeśli uruchamiasz z kopii roboczej repozytorium, openclaw plugins install ./path/to/local/matrix-plugin.
• Jeśli npm zgłasza należący do OpenClaw pakiet Matrix jako przestarzały, użyj dołączonego Pluginu z bieżącej spakowanej kompilacji OpenClaw albo lokalnej ścieżki kopii roboczej, dopóki nie zostanie opublikowany nowszy pakiet npm.

​

Jeśli zaszyfrowana historia nadal nie wraca

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

​

Jeśli chcesz zacząć od nowa dla przyszłych wiadomości

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

​

Powiązane

• Matrix: konfiguracja kanału.
• Reguły push Matrix: kierowanie powiadomień.
• Doctor: kontrola kondycji i wyzwalacz automatycznej migracji.
• Przewodnik migracji: wszystkie ścieżki migracji (przeniesienia maszyn, importy między systemami).
• Plugins: instalacja i rejestracja Pluginu.