Matrix 마이그레이션

• Plugin은 @openclaw/matrix로 유지됩니다.
• 채널은 matrix로 유지됩니다.
• 구성은 channels.matrix 아래에 유지됩니다.
• 캐시된 자격 증명은 ~/.openclaw/credentials/matrix/ 아래에 유지됩니다.
• 런타임 상태는 ~/.openclaw/matrix/ 아래에 유지됩니다.

​

마이그레이션이 자동으로 수행하는 작업

• 소스 설치는 업데이트 흐름 중 openclaw doctor --fix를 실행한 다음 기본적으로 Gateway를 다시 시작합니다.
• 패키지 관리자 설치는 패키지를 업데이트하고 비대화형 doctor 단계를 실행한 다음, 시작이 Matrix 마이그레이션을 완료할 수 있도록 기본 Gateway 재시작에 의존합니다.
• openclaw update --no-restart를 사용하는 경우, 나중에 openclaw doctor --fix를 실행하고 Gateway를 다시 시작할 때까지 시작 기반 Matrix 마이그레이션이 지연됩니다.

• ~/Backups/openclaw-migrations/ 아래에 사전 마이그레이션 스냅샷 생성 또는 재사용
• 캐시된 Matrix 자격 증명 재사용
• 동일한 계정 선택 및 channels.matrix 구성 유지
• 가장 오래된 평면 Matrix 동기화 저장소를 현재 계정 범위 위치로 이동
• 대상 계정을 안전하게 확인할 수 있을 때 가장 오래된 평면 Matrix 암호화 저장소를 현재 계정 범위 위치로 이동
• 해당 키가 로컬에 있는 경우, 이전 rust 암호화 저장소에서 이전에 저장된 Matrix 룸 키 백업 복호화 키 추출
• 나중에 액세스 토큰이 변경될 때 동일한 Matrix 계정, 홈서버, 사용자에 대해 가장 완전한 기존 토큰 해시 저장소 루트 재사용
• Matrix 액세스 토큰이 변경되었지만 계정/디바이스 ID가 동일하게 유지된 경우 보류 중인 암호화 상태 복원 메타데이터를 찾기 위해 형제 토큰 해시 저장소 루트 스캔
• 다음 Matrix 시작 시 백업된 룸 키를 새 암호화 저장소로 복원

• OpenClaw는 성공적인 스냅샷 후 ~/.openclaw/matrix/migration-snapshot.json에 마커 파일을 작성하여 이후 시작 및 복구 단계에서 동일한 아카이브를 재사용할 수 있게 합니다.
• 이러한 자동 Matrix 마이그레이션 스냅샷은 구성 + 상태만 백업합니다(includeWorkspace: false).
• Matrix에 경고 전용 마이그레이션 상태만 있는 경우, 예를 들어 userId 또는 accessToken이 아직 없기 때문에 OpenClaw는 실행 가능한 Matrix 변경이 없으므로 아직 스냅샷을 만들지 않습니다.
• 스냅샷 단계가 실패하면 OpenClaw는 복구 지점 없이 상태를 변경하는 대신 해당 실행의 Matrix 마이그레이션을 건너뜁니다.

• 가장 오래된 평면 Matrix 저장소(~/.openclaw/matrix/bot-storage.json 및 ~/.openclaw/matrix/crypto/)는 단일 저장소 레이아웃에서 왔으므로 OpenClaw는 이를 확인된 하나의 Matrix 계정 대상으로만 마이그레이션할 수 있습니다.
• 이미 계정 범위가 지정된 레거시 Matrix 저장소는 구성된 Matrix 계정별로 감지되고 준비됩니다.

​

마이그레이션이 자동으로 수행할 수 없는 작업

• 백업된 적이 없는 로컬 전용 룸 키
• homeserver, userId 또는 accessToken을 아직 사용할 수 없어 대상 Matrix 계정을 확인할 수 없는 경우의 암호화 상태
• 여러 Matrix 계정이 구성되어 있지만 channels.matrix.defaultAccount가 설정되지 않은 경우 하나의 공유 평면 Matrix 저장소 자동 마이그레이션
• 표준 Matrix 패키지 대신 저장소 경로에 고정된 사용자 지정 Plugin 경로 설치
• 이전 저장소에 백업된 키는 있었지만 복호화 키를 로컬에 보관하지 않은 경우의 누락된 복구 키

• 사용자 지정 Matrix Plugin 경로 설치는 Gateway 시작과 openclaw doctor 모두에서 표시됩니다.

​

권장 업그레이드 흐름

1. OpenClaw와 Matrix Plugin을 일반적인 방식으로 업데이트합니다. Matrix 마이그레이션을 즉시 완료할 수 있도록 --no-restart 없이 일반 openclaw update를 사용하는 것을 권장합니다.
2. 다음을 실행합니다.
   openclaw doctor --fix
   
   Matrix에 실행 가능한 마이그레이션 작업이 있으면 doctor가 먼저 사전 마이그레이션 스냅샷을 만들거나 재사용하고 아카이브 경로를 출력합니다.
3. Gateway를 시작하거나 다시 시작합니다.
4. 현재 검증 및 백업 상태를 확인합니다.
   openclaw matrix verify status
   openclaw matrix verify backup status
   
5. 복구하려는 Matrix 계정의 복구 키를 계정별 환경 변수에 넣습니다. 단일 기본 계정의 경우 MATRIX_RECOVERY_KEY로 충분합니다. 여러 계정의 경우 계정마다 하나의 변수를 사용하세요. 예: MATRIX_RECOVERY_KEY_ASSISTANT, 그리고 명령에 --account assistant를 추가하세요.
6. OpenClaw가 복구 키가 필요하다고 알려주면 일치하는 계정에 대해 명령을 실행합니다.
   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. 이 디바이스가 아직 검증되지 않았다면 일치하는 계정에 대해 명령을 실행합니다.
   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
   
   복구 키가 승인되고 백업을 사용할 수 있지만 Cross-signing verified가 여전히 no인 경우, 다른 Matrix 클라이언트에서 자체 검증을 완료하세요.
   openclaw matrix verify self
   
   다른 Matrix 클라이언트에서 요청을 수락하고 이모지 또는 숫자를 비교한 뒤, 일치할 때만 yes를 입력하세요. 명령은 Cross-signing verified가 yes가 된 후에만 성공적으로 종료됩니다.
8. 복구할 수 없는 오래된 기록을 의도적으로 포기하고 이후 메시지를 위한 새 백업 기준선을 원한다면 다음을 실행합니다.
   openclaw matrix verify backup reset --yes
   
9. 서버 측 키 백업이 아직 없다면 이후 복구를 위해 하나를 만듭니다.
   openclaw matrix verify bootstrap
   

​

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

1. 암호화된 마이그레이션을 실행할 수 있는 경우, 시작 또는 openclaw doctor --fix가 사전 마이그레이션 스냅샷을 만들거나 재사용합니다.
2. 시작 또는 openclaw doctor --fix가 활성 Matrix Plugin 설치를 통해 이전 Matrix 암호화 저장소를 검사합니다.
3. 백업 복호화 키가 발견되면 OpenClaw는 이를 새 복구 키 흐름에 기록하고 룸 키 복원을 보류 중으로 표시합니다.
4. 다음 Matrix 시작 시 OpenClaw는 백업된 룸 키를 새 암호화 저장소로 자동 복원합니다.

​

일반적인 메시지와 의미

​

업그레이드 및 감지 메시지

• 의미: 이전 디스크 Matrix 상태가 감지되어 현재 레이아웃으로 마이그레이션되었습니다.
• 해야 할 일: 같은 출력에 경고도 포함되어 있지 않다면 아무것도 하지 않아도 됩니다.

• 의미: OpenClaw가 Matrix 상태를 변경하기 전에 복구 아카이브를 만들었습니다.
• 해야 할 일: 마이그레이션이 성공했음을 확인할 때까지 출력된 아카이브 경로를 보관하세요.

• 의미: OpenClaw가 기존 Matrix 마이그레이션 스냅샷 마커를 찾았고 중복 백업을 만드는 대신 해당 아카이브를 재사용했습니다.
• 해야 할 일: 마이그레이션이 성공했음을 확인할 때까지 출력된 아카이브 경로를 보관하세요.

• 의미: 이전 Matrix 상태가 존재하지만 Matrix가 구성되지 않아 OpenClaw가 이를 현재 Matrix 계정에 매핑할 수 없습니다.
• 해야 할 일: channels.matrix를 구성한 다음 openclaw doctor --fix를 다시 실행하거나 Gateway를 다시 시작하세요.

• 의미: OpenClaw가 이전 상태를 찾았지만 아직 정확한 현재 계정/디바이스 루트를 결정할 수 없습니다.
• 해야 할 일: 작동하는 Matrix 로그인으로 Gateway를 한 번 시작하거나, 캐시된 자격 증명이 존재한 뒤 openclaw doctor --fix를 다시 실행하세요.

• 의미: OpenClaw가 하나의 공유 평면 Matrix 저장소를 찾았지만, 어떤 이름의 Matrix 계정이 이를 받아야 하는지 추측하지 않습니다.
• 해야 할 일: channels.matrix.defaultAccount를 의도한 계정으로 설정한 다음 openclaw doctor --fix를 다시 실행하거나 Gateway를 다시 시작하세요.

• 의미: 새 계정 범위 위치에 이미 동기화 또는 암호화 저장소가 있으므로 OpenClaw가 이를 자동으로 덮어쓰지 않았습니다.
• 해야 할 일: 충돌하는 대상을 수동으로 제거하거나 이동하기 전에 현재 계정이 올바른 계정인지 확인하세요.

• 의미: OpenClaw가 이전 Matrix 상태를 이동하려고 했지만 파일 시스템 작업이 실패했습니다.
• 해야 할 일: 파일 시스템 권한과 디스크 상태를 검사한 다음 openclaw doctor --fix를 다시 실행하세요.

• 의미: OpenClaw가 이전 암호화된 Matrix 저장소를 찾았지만, 이를 연결할 현재 Matrix 구성이 없습니다.
• 해야 할 일: channels.matrix를 구성한 다음 openclaw doctor --fix를 다시 실행하거나 Gateway를 다시 시작하세요.

• 의미: 암호화된 저장소가 존재하지만 OpenClaw가 이 저장소가 어떤 현재 계정/디바이스에 속하는지 안전하게 결정할 수 없습니다.
• 해야 할 일: 작동하는 Matrix 로그인으로 Gateway를 한 번 시작하거나, 캐시된 자격 증명을 사용할 수 있게 된 뒤 openclaw doctor --fix를 다시 실행하세요.

• 의미: OpenClaw가 하나의 공유 평면 레거시 암호화 저장소를 찾았지만, 어떤 이름의 Matrix 계정이 이를 받아야 하는지 추측하지 않습니다.
• 해야 할 일: channels.matrix.defaultAccount를 의도한 계정으로 설정한 다음 openclaw doctor --fix를 다시 실행하거나 Gateway를 다시 시작하세요.

• 의미: OpenClaw가 이전 Matrix 상태를 감지했지만, 마이그레이션은 아직 누락된 ID 또는 자격 증명 데이터로 인해 차단되어 있습니다.
• 해야 할 일: Matrix 로그인 또는 구성 설정을 완료한 다음 openclaw doctor --fix를 다시 실행하거나 Gateway를 다시 시작하세요.

• 의미: OpenClaw가 오래된 암호화된 Matrix 상태를 찾았지만, 일반적으로 해당 저장소를 검사하는 Matrix Plugin의 헬퍼 엔트리포인트를 로드할 수 없었습니다.
• 조치: Matrix Plugin을 다시 설치하거나 복구한 다음(openclaw plugins install @openclaw/matrix, 또는 repo checkout의 경우 openclaw plugins install ./path/to/local/matrix-plugin), openclaw doctor --fix를 다시 실행하거나 gateway를 재시작하세요.

• 의미: OpenClaw가 plugin 루트를 벗어나거나 plugin 경계 검사를 통과하지 못하는 헬퍼 파일 경로를 발견했으므로, 해당 파일 가져오기를 거부했습니다.
• 조치: 신뢰할 수 있는 경로에서 Matrix Plugin을 다시 설치한 다음, openclaw doctor --fix를 다시 실행하거나 gateway를 재시작하세요.

• 의미: OpenClaw가 복구 스냅샷을 먼저 만들 수 없어 Matrix 상태 변경을 거부했습니다.
• 조치: 백업 오류를 해결한 다음, openclaw doctor --fix를 다시 실행하거나 gateway를 재시작하세요.

• 의미: Matrix 클라이언트 측 fallback이 오래된 flat storage를 찾았지만, 이동에 실패했습니다. 이제 OpenClaw는 새 저장소로 조용히 시작하는 대신 해당 fallback을 중단합니다.
• 조치: 파일 시스템 권한 또는 충돌을 확인하고, 기존 상태를 그대로 유지한 뒤 오류를 수정한 후 다시 시도하세요.

• 의미: Matrix가 경로 설치로 고정되어 있어, mainline 업데이트가 repo의 표준 Matrix 패키지로 자동 교체하지 않습니다.
• 조치: 기본 Matrix Plugin으로 돌아가려면 openclaw plugins install @openclaw/matrix로 다시 설치하세요.

​

암호화된 상태 복구 메시지

• 의미: 백업된 room key가 새 crypto store로 성공적으로 복원되었습니다.
• 조치: 일반적으로 아무것도 하지 않아도 됩니다.

• 의미: 일부 오래된 room key가 기존 로컬 저장소에만 있었고 Matrix 백업에 업로드된 적이 없습니다.
• 조치: 다른 검증된 클라이언트에서 해당 키를 수동으로 복구할 수 없다면, 일부 오래된 암호화 기록은 계속 사용할 수 없을 수 있습니다.

• 의미: 백업은 있지만 OpenClaw가 recovery key를 자동으로 복구할 수 없었습니다.
• 조치: printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin을 실행하세요.

• 의미: OpenClaw가 오래된 암호화 저장소를 찾았지만, 복구 준비를 할 만큼 안전하게 검사할 수 없었습니다.
• 조치: openclaw doctor --fix를 다시 실행하세요. 반복되면 기존 상태 디렉터리를 그대로 유지하고, 다른 검증된 Matrix 클라이언트와 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin을 사용해 복구하세요.

• 의미: OpenClaw가 백업 키 충돌을 감지했고 현재 recovery-key 파일을 자동으로 덮어쓰지 않았습니다.
• 조치: 복원 명령을 다시 시도하기 전에 어떤 recovery key가 올바른지 확인하세요.

• 의미: 이는 오래된 저장소 형식의 근본적인 한계입니다.
• 조치: 백업된 키는 여전히 복원할 수 있지만, 로컬에만 있던 암호화 기록은 계속 사용할 수 없을 수 있습니다.

• 의미: 새 plugin이 복원을 시도했지만 Matrix가 오류를 반환했습니다.
• 조치: openclaw matrix verify backup status를 실행한 다음, 필요한 경우 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin으로 다시 시도하세요.

​

수동 복구 메시지

• 의미: OpenClaw는 백업 키가 있어야 함을 알고 있지만, 이 장치에서 활성화되어 있지 않습니다.
• 조치: openclaw matrix verify backup restore를 실행하거나, 필요한 경우 MATRIX_RECOVERY_KEY를 설정하고 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin을 실행하세요.

• 의미: 이 장치에는 현재 recovery key가 저장되어 있지 않습니다.
• 조치: MATRIX_RECOVERY_KEY를 설정하고 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin을 실행한 다음, 백업을 복원하세요.

• 의미: 저장된 키가 활성 Matrix 백업과 일치하지 않습니다.
• 조치: MATRIX_RECOVERY_KEY를 올바른 키로 설정하고 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin을 실행하세요.

• 의미: 백업은 있지만, 이 장치가 아직 cross-signing chain을 충분히 신뢰하지 않습니다.
• 조치: MATRIX_RECOVERY_KEY를 설정하고 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin을 실행하세요.

• 의미: recovery key가 필요한 복구 단계에서 recovery key를 제공하지 않았습니다.
• 조치: 예를 들어 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin처럼 --recovery-key-stdin을 사용해 명령을 다시 실행하세요.

• 의미: 제공된 키를 파싱할 수 없거나 예상 형식과 일치하지 않았습니다.
• 조치: Matrix 클라이언트 또는 recovery-key 파일의 정확한 recovery key로 다시 시도하세요.

• 의미: OpenClaw가 recovery key를 적용할 수는 있었지만, Matrix가 아직 이 장치에 대한 전체 cross-signing identity trust를 설정하지 않았습니다. 명령 출력에서 Recovery key accepted, Backup usable, Cross-signing verified, Device verified by owner를 확인하세요.
• 조치: openclaw matrix verify self를 실행하고, 다른 Matrix 클라이언트에서 요청을 수락한 뒤 SAS를 비교하고 일치할 때만 yes를 입력하세요. 이 명령은 성공을 보고하기 전에 전체 Matrix identity trust가 설정될 때까지 기다립니다. 현재 cross-signing identity를 의도적으로 교체하려는 경우에만 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing 을 사용하세요.

• 의미: secret storage가 이 장치에서 활성 백업 세션을 만들지 못했습니다.
• 조치: 먼저 장치를 검증한 다음 openclaw matrix verify backup status로 다시 확인하세요.

• 의미: 장치 검증이 완료될 때까지 이 장치는 secret storage에서 복원할 수 없습니다.
• 조치: 먼저 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin을 실행하세요.

​

사용자 지정 plugin 설치 메시지

• 의미: plugin 설치 기록이 더 이상 존재하지 않는 로컬 경로를 가리킵니다.
• 조치: openclaw plugins install @openclaw/matrix로 다시 설치하거나, repo checkout에서 실행 중이라면 openclaw plugins install ./path/to/local/matrix-plugin을 사용하세요.

​

암호화 기록이 여전히 돌아오지 않는 경우

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

​

이후 메시지를 위해 새로 시작하려는 경우

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

​

관련 항목

• Matrix: 채널 설정 및 구성.
• Matrix push rules: 알림 라우팅.
• Doctor: 상태 검사 및 자동 migration trigger.
• Migration guide: 모든 migration 경로(머신 이동, cross-system import).
• Plugins: plugin 설치 및 등록.