Migracja Matrix

• Plugin pozostaje @openclaw/matrix
• kanał pozostaje matrix
• konfiguracja pozostaje w channels.matrix
• zapisane w pamięci podręcznej dane uwierzytelniające pozostają w ~/.openclaw/credentials/matrix/
• stan środowiska wykonawczego pozostaje w ~/.openclaw/matrix/

​

Co migracja wykonuje automatycznie

• instalacje ze źródeł uruchamiają openclaw doctor --fix podczas procesu 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 oparta na uruchamianiu zostaje odłożona do czasu, aż później uruchomisz openclaw doctor --fix i zrestartujesz Gateway

• utworzenie albo ponowne wykorzystanie migawki sprzed migracji w ~/Backups/openclaw-migrations/
• ponowne użycie zapisanych w pamięci podręcznej danych uwierzytelniających Matrix
• zachowanie tego samego wyboru konta i konfiguracji channels.matrix
• przeniesienie najstarszego płaskiego magazynu synchronizacji Matrix do bieżącej lokalizacji o zakresie konta
• przeniesienie najstarszego płaskiego magazynu kryptograficznego Matrix do bieżącej lokalizacji o zakresie konta, gdy konto docelowe można bezpiecznie rozpoznać
• wyodrębnienie wcześniej zapisanego klucza odszyfrowywania kopii zapasowej kluczy pokoi Matrix ze starego magazynu kryptograficznego rust, gdy taki klucz istnieje lokalnie
• ponowne użycie 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 zapisanych w kopii zapasowej kluczy pokoi 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 użyć tego samego archiwum.
• Te automatyczne migawki migracji Matrix zapisują tylko konfigurację i stan (includeWorkspace: false).
• Jeśli Matrix ma tylko ostrzegawczy stan migracji, na przykład dlatego, że nadal brakuje userId albo accessToken, OpenClaw nie tworzy jeszcze migawki, ponieważ żadna mutacja Matrix nie jest wykonalna.
• Jeśli krok migawki się nie powiedzie, OpenClaw pomija migrację Matrix w tym przebiegu zamiast modyfikować stan bez punktu odzyskiwania.

• najstarszy płaski magazyn Matrix (~/.openclaw/matrix/bot-storage.json i ~/.openclaw/matrix/crypto/) pochodził z układu jednego magazynu, więc OpenClaw może przenieść go tylko do jednego rozpoznanego celu konta Matrix
• starsze magazyny Matrix już o zakresie konta są wykrywane i przygotowywane osobno dla każdego skonfigurowanego konta Matrix

​

Czego migracja nie może zrobić automatycznie

• kluczy pokoi dostępnych tylko lokalnie, które nigdy nie zostały zapisane w kopii zapasowej
• zaszyfrowanego stanu, gdy docelowego konta Matrix nie można jeszcze rozpoznać, ponieważ homeserver, userId albo accessToken nadal są niedostępne
• automatycznej migracji jednego współdzielonego płaskiego magazynu Matrix, gdy skonfigurowano wiele kont Matrix, ale channels.matrix.defaultAccount nie jest ustawione
• niestandardowych instalacji Plugin ze ścieżki, przypiętych do ścieżki repozytorium zamiast do standardowego pakietu Matrix
• brakującego klucza odzyskiwania, gdy stary magazyn miał klucze zapisane w kopii zapasowej, ale nie zachował lokalnie klucza odszyfrowywania

• niestandardowe instalacje Plugin Matrix ze ścieżki są zgłaszane zarówno przez uruchamianie Gateway, jak i openclaw doctor

​

Zalecany przebieg aktualizacji

1. Zaktualizuj OpenClaw i Plugin Matrix w zwykły sposób. Preferuj zwykłe openclaw update bez --no-restart, aby uruchamianie mogło od razu dokończyć migrację Matrix.
2. Uruchom:
   openclaw doctor --fix
   
   Jeśli Matrix ma wykonalną pracę migracyjną, doctor najpierw utworzy albo ponownie wykorzysta migawkę sprzed migracji i wypisze ścieżkę archiwum.
3. Uruchom albo 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 naprawianego konta Matrix w zmiennej środowiskowej właściwej 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 odpowiedniego 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 odpowiedniego 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 i 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 albo liczby dziesiętne i wpisz yes tylko wtedy, gdy się zgadzają. Polecenie kończy się powodzeniem dopiero po tym, jak Cross-signing verified zmieni się na yes.
8. Jeśli celowo porzucasz niemożliwą do odzyskania starą historię i chcesz świeżą bazę 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ą na potrzeby przyszłego odzyskiwania:
   openclaw matrix verify bootstrap
   

​

Jak działa migracja szyfrowania

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

​

Typowe komunikaty i ich znaczenie

​

Komunikaty aktualizacji i wykrywania

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

• Znaczenie: OpenClaw utworzył archiwum odzyskiwania przed zmodyfikowaniem stanu Matrix.
• Co zrobić: zachowaj wypisaną ścieżkę archiwum do czasu potwierdzenia, że migracja się powiodła.

• Znaczenie: OpenClaw znalazł istniejący znacznik migawki migracji Matrix i ponownie użył tego archiwum zamiast tworzyć duplikat kopii zapasowej.
• Co zrobić: zachowaj wypisaną ścieżkę archiwum do czasu potwierdzenia, że migracja się powiodła.

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

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

• 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 albo zrestartuj Gateway.

• Znaczenie: nowa lokalizacja o zakresie konta ma już magazyn synchronizacji albo magazyn kryptograficzny, więc OpenClaw nie nadpisał go automatycznie.
• Co zrobić: sprawdź, czy bieżące konto jest właściwe, zanim ręcznie usuniesz albo przeniesiesz konfliktujący cel.

• Znaczenie: OpenClaw próbował przenieść stary stan Matrix, ale operacja na systemie 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 albo 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 raz Gateway z działającym logowaniem Matrix albo ponownie uruchom openclaw doctor --fix, gdy zapisane w pamięci podręcznej dane uwierzytelniające są dostępne.

• 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 albo zrestartuj Gateway.

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

• Znaczenie: OpenClaw znalazł stary zaszyfrowany stan Matrix, ale nie mógł załadować punktu wejścia pomocnika z pluginu Matrix, który normalnie 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 w przypadku checkoutu repozytorium), a następnie uruchom ponownie openclaw doctor --fix albo zrestartuj gateway.

• Znaczenie: OpenClaw znalazł ścieżkę pliku pomocnika, 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 uruchom ponownie openclaw doctor --fix albo zrestartuj gateway.

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

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

• Znaczenie: Matrix jest przypięty do instalacji ze ścieżki, więc aktualizacje głównej linii 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.

​

Komunikaty odzyskiwania zaszyfrowanego stanu

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

• Znaczenie: niektóre stare klucze pokoi istniały tylko w starym lokalnym magazynie i nigdy nie zostały przesłane do kopii zapasowej Matrix.
• Co zrobić: należy się spodziewać, ż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ć: uruchom ponownie openclaw doctor --fix. Jeśli problem się powtórzy, pozostaw stary katalog stanu bez zmian i odzyskaj dane za pomocą 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 klucza odzyskiwania.
• Co zrobić: sprawdź, który klucz odzyskiwania jest poprawny, zanim ponownie spróbujesz wykonać 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 próbował przywrócić dane, ale Matrix zwrócił błąd.
• Co zrobić: uruchom openclaw matrix verify backup status, a następnie w razie potrzeby spróbuj ponownie z printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin.

​

Komunikaty ręcznego odzyskiwania

• Znaczenie: OpenClaw wie, że powinieneś mieć 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 cross-signing.
• Co zrobić: ustaw MATRIX_RECOVERY_KEY i uruchom printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.

• Znaczenie: podjęto próbę kroku odzyskiwania bez podania klucza odzyskiwania, choć był 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ć: spróbuj ponownie z dokładnym kluczem odzyskiwania z klienta Matrix albo pliku klucza odzyskiwania.

• Znaczenie: OpenClaw mógł zastosować klucz odzyskiwania, ale Matrix nadal nie ustanowił pełnego zaufania tożsamości cross-signing dla tego urządzenia. Sprawdź wynik 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. To 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ść cross-signing.

• 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 przywrócić danych 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 lokalną ścieżkę, która już nie istnieje.
• Co zrobić: zainstaluj ponownie za pomocą openclaw plugins install @openclaw/matrix albo, jeśli uruchamiasz z checkoutu repozytorium, openclaw plugins install ./path/to/local/matrix-plugin.

​

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 i ustawienie kanału.
• Reguły push Matrix: routing powiadomień.
• Doctor: kontrola stanu i wyzwalacz automatycznej migracji.
• Przewodnik migracji: wszystkie ścieżki migracji (przenoszenie maszyn, importy między systemami).
• Plugins: instalacja i rejestracja pluginów.