OpenClaw Matrix 플러그인 마이그레이션 가이드

자동 마이그레이션 항목

Gateway가 시작되거나 openclaw doctor --fix를 실행할 때, OpenClaw는 이전 Matrix 상태를 자동으로 복구하려고 시도해요. 디스크 상태를 변경하는 마이그레이션 단계가 실행되기 전에, OpenClaw는 전용 복구 스냅샷을 생성하거나 기존 것을 재사용하죠.

openclaw update를 사용할 때의 구체적인 트리거는 OpenClaw 설치 방식에 따라 달라져요:

소스 설치: 업데이트 과정 중에 openclaw doctor --fix를 실행하고, 기본적으로 Gateway를 재시작해요.
패키지 매니저 설치: 패키지를 업데이트하고 비대화형(non-interactive) doctor 과정을 거친 뒤, Gateway 재시작을 통해 마이그레이션을 완료해요.
openclaw update --no-restart 사용 시: 나중에 openclaw doctor --fix를 실행하고 Gateway를 재시작할 때까지 마이그레이션이 연기돼요.

자동 마이그레이션에는 다음 내용이 포함돼요:

~/Backups/openclaw-migrations/ 아래에 마이그레이션 전 스냅샷 생성 또는 재사용
캐시된 Matrix credentials 재사용
동일한 계정 선택 및 channels.matrix 설정 유지
이전의 단일(flat) Matrix sync store를 현재의 계정별(account-scoped) 위치로 이동
대상 계정을 안전하게 확인할 수 있는 경우, 이전의 단일 Matrix crypto store를 현재의 계정별 위치로 이동
로컬에 키가 존재하는 경우, 이전 rust crypto store에서 저장된 Matrix room-key backup 복호화 키 추출
나중에 access token이 변경되더라도 동일한 Matrix 계정, homeserver, 사용자에 대해 가장 완전한 기존 token-hash storage root를 재사용
Matrix access token은 변경되었지만 계정/기기 ID가 동일한 경우, 보류 중인 암호화 상태 복구 메타데이터를 찾기 위해 형제 token-hash storage root를 스캔
다음 Matrix 시작 시 백업된 room keys를 새 crypto store로 복구

스냅샷 상세 정보:

OpenClaw는 스냅샷 성공 후 ~/.openclaw/matrix/migration-snapshot.json에 마커 파일을 작성해서 나중에 다시 시작하거나 복구할 때 동일한 아카이브를 재사용할 수 있게 해요.
이 자동 마이그레이션 스냅샷은 설정과 상태만 백업해요 (includeWorkspace: false).
userId나 accessToken이 누락되는 등 경고 수준의 상태인 경우, 실행할 수 있는 작업이 없으므로 스냅샷을 생성하지 않아요.
스냅샷 단계에서 실패하면, 복구 지점 없이 상태를 변경하지 않도록 해당 실행에서는 마이그레이션을 건너뛰어요.

다중 계정 업그레이드 관련:

이전의 단일 Matrix store(~/.openclaw/matrix/bot-storage.json 및 ~/.openclaw/matrix/crypto/)는 단일 저장소 구조였기 때문에, OpenClaw는 이를 하나의 확정된 Matrix 계정 대상으로만 마이그레이션할 수 있어요.
이미 계정별로 구분된 레거시 Matrix store는 구성된 Matrix 계정별로 감지되고 준비돼요.

자동 마이그레이션이 불가능한 항목

이전의 공개 Matrix plugin은 Matrix room-key backup을 자동으로 생성하지 않았어요. 로컬 crypto 상태를 유지하고 기기 인증을 요청하긴 했지만, room keys가 homeserver에 백업되는 것을 보장하지는 않았죠.

이 때문에 일부 암호화된 설치 환경은 부분적으로만 마이그레이션될 수 있어요.

OpenClaw가 자동으로 복구할 수 없는 항목은 다음과 같아요:

백업된 적 없는 로컬 전용 room keys
homeserver, userId, 또는 accessToken을 아직 사용할 수 없어 대상 Matrix 계정을 확인할 수 없는 경우의 암호화 상태
여러 Matrix 계정이 설정되어 있지만 channels.matrix.defaultAccount가 설정되지 않은 상태에서 하나의 공유 단일 Matrix store를 자동 마이그레이션하는 경우
표준 Matrix 패키지 대신 특정 repo path에 고정된 커스텀 plugin path 설치본
이전 store에 백업된 키는 있지만 복호화 키를 로컬에 보관하지 않은 경우의 누락된 recovery key

현재 경고 범위:

커스텀 Matrix plugin path 설치는 Gateway 시작 시와 openclaw doctor 실행 시 모두 표시돼요.

만약 이전 설치 환경에 백업되지 않은 로컬 전용 암호화 히스토리가 있다면, 업그레이드 후에 일부 오래된 암호화 메시지를 읽지 못할 수도 있어요.

권장 업그레이드 절차

OpenClaw와 Matrix plugin을 평소처럼 업데이트하세요. --no-restart 옵션 없이 openclaw update를 사용하는 것을 추천해요. 그래야 시작할 때 Matrix 마이그레이션을 즉시 완료할 수 있거든요.
다음 명령어를 실행하세요:
Terminal window
```
openclaw doctor --fix
```
Matrix에 실행 가능한 마이그레이션 작업이 있다면, doctor가 먼저 마이그레이션 전 snapshot을 생성하거나 재사용하고 archive 경로를 출력할 거예요.
Gateway를 시작하거나 재시작하세요.

현재 인증 및 백업 상태를 확인해 보세요:

openclaw matrix verify status
openclaw matrix verify backup status

만약 OpenClaw가 recovery key가 필요하다고 안내하면, 이렇게 실행하세요:
Terminal window
```
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"
```
이 기기가 여전히 인증되지 않은 상태라면, 다음 명령어를 실행하세요:
Terminal window
```
openclaw matrix verify device "<your-recovery-key>"
```
복구 불가능한 이전 히스토리를 의도적으로 삭제하고 향후 메시지를 위해 새로운 백업 기준점을 만들고 싶다면, 이렇게 하세요:
Terminal window
```
openclaw matrix verify backup reset --yes
```
아직 서버 측에 key 백업이 존재하지 않는다면, 나중에 복구할 수 있도록 백업을 생성하세요:
Terminal window
```
openclaw matrix verify bootstrap
```

암호화 마이그레이션 작동 방식

암호화 마이그레이션은 두 단계로 진행돼요:

암호화 마이그레이션이 가능한 상태라면, 시작 시점이나 openclaw doctor --fix 실행 시 마이그레이션 전 snapshot을 생성하거나 재사용해요.
시작 시점이나 openclaw doctor --fix가 현재 활성화된 Matrix plugin 설치본을 통해 이전 Matrix crypto store를 검사해요.
백업 복호화 key를 찾으면, OpenClaw가 이를 새로운 recovery-key 흐름에 기록하고 room-key 복구를 대기(pending) 상태로 표시해요.
다음 Matrix 시작 시, OpenClaw가 백업된 room key를 새로운 crypto store로 자동 복구해요.

만약 이전 store에 한 번도 백업되지 않은 room key가 있다면, 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 상태가 존재하지만, Matrix가 설정되지 않아 OpenClaw가 이를 현재 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가 오래된 상태를 찾았지만, 아직 정확한 현재 계정이나 디바이스 루트를 결정할 수 없는 상태예요.
조치 방법: 작동하는 Matrix 로그인 정보로 Gateway를 한 번 시작하거나, 캐시된 자격 증명이 생긴 후에 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 (...)

의미: 새로운 계정 범위의 위치에 이미 sync 또는 crypto 저장소가 있어서 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가 이것이 현재 어떤 계정이나 디바이스에 속하는지 안전하게 결정할 수 없어요.
조치 방법: 작동하는 Matrix 로그인 정보로 Gateway를 한 번 시작하거나, 캐시된 자격 증명을 사용할 수 있게 된 후에 openclaw doctor --fix를 다시 실행하세요.

Legacy Matrix encrypted state detected at ... but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set.

의미: OpenClaw가 공유된 단일 레거시 crypto 저장소를 찾았지만, 이름이 지정된 여러 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 상태를 감지했지만, ID나 자격 증명 데이터가 누락되어 마이그레이션이 차단된 상태예요.
조치 방법: 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 플러그인의 헬퍼 엔트리포인트를 로드할 수 없어요.
조치 방법: Matrix 플러그인을 다시 설치하거나 복구(openclaw plugins install @openclaw/matrix 실행, 또는 레포지토리 체크아웃의 경우 openclaw plugins install ./path/to/local/matrix-plugin 실행)한 다음, openclaw doctor --fix를 다시 실행하거나 Gateway를 재시작하세요.

Matrix plugin helper path is unsafe: ... Reinstall @openclaw/matrix and try again.

의미: OpenClaw가 플러그인 루트를 벗어나거나 플러그인 경계 검사에 실패한 헬퍼 파일 경로를 발견하여 임포트를 거부했어요.
조치 방법: 신뢰할 수 있는 경로에서 Matrix 플러그인을 다시 설치한 다음, 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 클라이언트 측 폴백(fallback)이 오래된 저장소를 찾았지만 이동에 실패했어요. OpenClaw는 빈 저장소로 새로 시작하는 대신 해당 폴백 과정을 중단합니다.
조치 방법: 파일 시스템 권한이나 충돌 여부를 확인하고, 기존 상태를 그대로 유지한 채 오류를 수정한 후 다시 시도하세요.

Matrix is installed from a custom path: ...

의미: Matrix가 특정 경로 설치로 고정되어 있어, 메인라인 업데이트 시 레포지토리의 표준 Matrix 패키지로 자동 교체되지 않아요.
조치 방법: 기본 Matrix 플러그인으로 돌아가고 싶을 때 openclaw plugins install @openclaw/matrix로 다시 설치하세요.

암호화 상태 복구 메시지

matrix: restored X/Y room key(s) from legacy encrypted-state backup

의미: 백업된 룸 키가 새로운 crypto 저장소로 성공적으로 복구되었어요.
조치 방법: 보통은 아무것도 하지 않으셔도 돼요.

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 <key>" after upgrade if they have the recovery key.

의미: 백업은 존재하지만 OpenClaw가 복구 키를 자동으로 복구할 수 없었어요.
조치 방법: openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"를 실행하세요.

Failed inspecting legacy Matrix encrypted state for account "..." (...): ...

의미: OpenClaw가 오래된 암호화 저장소를 찾았지만, 복구를 준비할 만큼 안전하게 검사할 수 없었어요.
조치 방법: openclaw doctor --fix를 다시 실행하세요. 문제가 반복되면 기존 상태 디렉토리를 그대로 유지하고, 다른 인증된 Matrix 클라이언트와 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.

의미: 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: ...

의미: 새 플러그인이 복구를 시도했지만 Matrix가 오류를 반환했어요.
조치 방법: openclaw matrix verify backup status를 실행한 다음, 필요에 따라 openclaw matrix verify backup restore --recovery-key "<your-recovery-key>"로 다시 시도하세요.

수동 복구 메시지

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를 실행하거나, 필요한 경우 --recovery-key를 함께 전달하세요.

Store a recovery key with 'openclaw matrix verify device <key>', then run 'openclaw matrix verify backup restore'.

의미: 이 디바이스에 현재 복구 키가 저장되어 있지 않아요.
조치 방법: 먼저 복구 키로 디바이스를 인증한 다음, 백업을 복구하세요.

Backup key mismatch on this device. Re-run 'openclaw matrix verify device <key>' with the matching recovery key.

의미: 저장된 키가 활성화된 Matrix 백업과 일치하지 않아요.
조치 방법: 올바른 키를 사용하여 openclaw matrix verify device "<your-recovery-key>"를 다시 실행하세요.

복구 불가능한 오래된 암호화 히스토리를 포기해도 괜찮다면, openclaw matrix verify backup reset --yes를 사용하여 현재 백업 기준점을 재설정할 수 있어요.

Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device <key>'.

의미: 백업은 존재하지만, 이 디바이스가 아직 교차 서명(cross-signing) 체인을 충분히 신뢰하지 못하고 있어요.
조치 방법: openclaw matrix verify device "<your-recovery-key>"를 다시 실행하세요.

Matrix recovery key is required

의미: 복구 키가 필요한 단계에서 키를 제공하지 않고 시도했어요.
조치 방법: 복구 키를 포함하여 명령어를 다시 실행하세요.

Invalid Matrix recovery key: ...

의미: 제공된 키를 파싱할 수 없거나 예상된 형식과 일치하지 않아요.
조치 방법: Matrix 클라이언트나 recovery-key 파일에 있는 정확한 복구 키로 다시 시도하세요.

Matrix device is still unverified after applying recovery key. Verify your recovery key and ensure cross-signing is available.

의미: 키가 적용되었지만 디바이스가 여전히 인증을 완료하지 못했어요.
조치 방법: 올바른 키를 사용했는지, 계정에서 교차 서명을 사용할 수 있는지 확인한 후 다시 시도하세요.

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 <key>' first.

의미: 디바이스 인증이 완료될 때까지 이 디바이스는 보안 저장소에서 복구할 수 없어요.
조치 방법: openclaw matrix verify device "<your-recovery-key>"를 먼저 실행하세요.

커스텀 플러그인 설치 메시지

Matrix is installed from a custom path that no longer exists: ...

의미: 플러그인 설치 기록이 더 이상 존재하지 않는 로컬 경로를 가리키고 있어요.
조치 방법: openclaw plugins install @openclaw/matrix로 다시 설치하세요. 레포지토리 체크아웃에서 실행 중이라면 openclaw plugins install ./path/to/local/matrix-plugin을 실행하세요.

암호화된 히스토리가 여전히 돌아오지 않는다면

다음 순서대로 체크해 보세요:

openclaw matrix verify status --verbose
openclaw matrix verify backup status --verbose
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose

백업 복구는 성공했지만 일부 오래된 룸의 히스토리가 여전히 보이지 않는다면, 해당 누락된 키들이 이전 플러그인에서 백업되지 않았을 가능성이 큽니다.

앞으로의 메시지를 위해 새로 시작하고 싶다면

복구할 수 없는 이전의 암호화된 히스토리를 잃어도 괜찮고, 앞으로를 위해 깨끗한 백업 베이스라인만 만들고 싶다면 다음 명령어를 순서대로 실행해 보세요.

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

만약 그 이후에도 디바이스가 여전히 인증되지 않은 상태라면, Matrix 클라이언트에서 SAS 이모지나 십진수 코드를 비교하고 서로 일치하는지 확인해서 인증을 완료해 주세요.

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.