Matrix migration

기준일: 2026-07-26
공식 기준: Matrix migration

Matrix migration 문서는 OpenClaw 공식 문서(channels/matrix-migration)를 한국어로 정리한 가이드입니다. How OpenClaw upgrades the previous Matrix plugin in place, including encrypted-state recovery limits and manual recovery steps. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

How OpenClaw upgrades the previous Matrix plugin in place, including encrypted-state recovery limits and manual recovery steps.

한국어 가이드 범위: channels/matrix-migration 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• What the migration does automatically
• Upgrading from OpenClaw releases older than 2026.4
• Recommended upgrade flow
• Common messages and what they mean
• Manual recovery messages
• If encrypted history still does not come back
• If you want to start fresh for future messages
• 관련 문서

상세 내용

본문

Upgrade from the previous public matrix plugin to the current implementation.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• the plugin stays @openclaw/matrix
• the channel stays matrix
• your config stays under channels.matrix
• cached credentials move into the shared state/openclaw.sqlite plugin state
• runtime state stays under ~/.openclaw/matrix/

What the migration does automatically

Matrix migration runs when you run openclaw doctor --fix. File-based sidecars next to the dedicated Matrix store retain their client-start fallback, but credential-file import is Doctor-only; runtime reads only canonical SQLite credential state.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• importing and verifying retired ~/.openclaw/credentials/matrix/credentials*.json files before archiving them
• keeping the same account selection and channels.matrix config
• importing file-based sidecar state (bot-storage.json sync cache, recovery-key.json, legacy-crypto-migration.json, IndexedDB snapshots) into Matrix SQLite state; migrated files are archived with a .migrated suffix
• reusing the most complete existing token-hash storage root for the same Matrix account, homeserver, user, and device when the access token changes later

Upgrading from OpenClaw releases older than 2026.4

Releases through the 2026.6 train also migrated the original flat single-store Matrix layout (~/.openclaw/matrix/bot-storage.json plus ~/.openclaw/matrix/crypto/) and prepared encrypted-state recovery from the old rust crypto store. Current releases no longer carry that migration.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Recommended upgrade flow

1. Update OpenClaw and the Matrix plugin normally. 2. Run:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw doctor --fix

openclaw matrix verify status
   openclaw matrix verify backup status

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

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

Common messages and what they mean

Failed migrating legacy Matrix client storage: ...

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Meaning: the Matrix client-side fallback found file-based sidecar state, but the import into SQLite failed. OpenClaw rolls back completed moves and aborts that fallback instead of silently starting with a fresh store.
• What to do: inspect filesystem permissions or conflicts, keep the old state intact, and retry after fixing the error.
• Meaning: Matrix is pinned to a path install, so mainline updates do not automatically replace it with the default Matrix package.
• What to do: reinstall with openclaw plugins install @openclaw/matrix when you want to return to the default Matrix plugin.
• Meaning: your plugin install record points at a local path that is gone.
• What to do: reinstall with openclaw plugins install @openclaw/matrix, or if you are running from a repo checkout, openclaw plugins install ./path/to/local/matrix-plugin. openclaw doctor --fix can also remove the stale Matrix plugin references for you.

Manual recovery messages

openclaw matrix verify status and openclaw matrix verify backup status print a Backup issue: line plus Next steps: guidance when the room-key backup is not healthy on this device:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Meaning: you tried a recovery step without supplying a recovery key when one was required.
• What to do: rerun the command with --recovery-key-stdin, for example printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin.
• Meaning: the provided key could not be parsed or did not match the expected format.
• What to do: retry with the exact recovery key from your Matrix client or recovery-key export.
• Meaning: the recovery key unlocked usable backup material, but Matrix has not established full cross-signing identity trust for this device. Check the command output for Recovery key accepted, Backup usable, Cross-signing verified, and Device verified by owner.
• What to do: run openclaw matrix verify self, accept the request in another Matrix client, compare the SAS, and type yes only when it matches. Use printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing only when you intentionally want to replace the current cross-signing identity.

Backup issue	Meaning	Fix
no room-key backup exists on the homeserver	nothing to restore from	openclaw matrix verify bootstrap to create a room key backup
backup decryption key is not loaded on this device	key exists but is not active here	openclaw matrix verify backup restore; if it still cannot load the key, pipe the recovery key via --recovery-key-stdin
backup decryption key could not be loaded from secret storage (...)	secret storage load failed or is unsupported	pipe the recovery key: printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin
backup key mismatch (...)	stored key does not match the active server backup	rerun verify backup restore --recovery-key-stdin with the active server backup key, or verify backup reset --yes for a fresh baseline
backup signature chain is not trusted by this device	device does not trust the cross-signing chain yet	verify device --recovery-key-stdin, then verify self from another verified client if trust is still incomplete
backup exists but is not active on this device	server backup present, local session inactive	verify the device first, then recheck with openclaw matrix verify backup status
backup trust state could not be fully determined	diagnostics were inconclusive	openclaw matrix verify status --verbose

If encrypted history still does not come back

If the backup restores successfully but some old rooms are still missing history, those missing keys were probably never backed up by the previous plugin.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

If you want to start fresh for future messages

If you accept losing unrecoverable old encrypted history and only want a clean backup baseline going forward, run these commands in order:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

관련 문서

주요 항목:

• Matrix: channel setup and config.
• Matrix push rules: notification routing.
• Doctor: health check and automatic migration trigger.
• Migration guide: all migration paths (machine moves, cross-system imports).
• Plugins: plugin install and registration.

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/channels/matrix-migration
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw doctor --fix

openclaw matrix verify status
   openclaw matrix verify backup status

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

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

openclaw matrix verify self

openclaw matrix verify backup reset --yes

관련 링크

• 공식 원문: channels/matrix-migration
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.