OpenClaw Matrix移行ガイド：自動アップグレードと復旧手順

自動で行われる移行内容

Gateway の起動時、または openclaw doctor --fix を実行した際、OpenClaw は古い Matrix の状態を自動的に修復しようとします。ディスク上の状態を変更するような Matrix 移行ステップが実行される前には、OpenClaw は専用のリカバリ用スナップショットを作成、または既存のものを再利用します。

openclaw update を使用する場合、実行されるタイミングは OpenClaw のインストール方法によって異なります。

ソースからインストールしている場合は、アップデートの流れの中で openclaw doctor --fix が実行され、その後デフォルトで Gateway が再起動します。
パッケージマネージャーでインストールしている場合は、パッケージが更新され、非対話形式の doctor パスが実行されます。その後、通常の Gateway 起動プロセスによって Matrix の移行が完了します。
openclaw update --no-restart を使用した場合は、次に openclaw doctor --fix を実行して Gateway を再起動するまで、起動時の Matrix 移行処理は保留されます。

自動移行には以下の内容が含まれます。

~/Backups/openclaw-migrations/ への移行前スナップショットの作成、または再利用。
キャッシュされた Matrix 認証情報の再利用。
アカウント選択および channels.matrix 設定の維持。
最も古いフラットな Matrix sync store を、現在のアカウントごとの保存場所へ移動。
ターゲットアカウントが安全に特定できる場合に、最も古いフラットな Matrix crypto store を現在のアカウントごとの場所へ移動。
古い rust crypto store にローカルの復号キーが存在する場合、以前保存された Matrix ルームキーのバックアップ復号キーを抽出。
後に access token が変更された際、同じ Matrix アカウント、homeserver、ユーザーに対して、最も完全な既存の token-hash ストレージルートを再利用。
Matrix の access token は変更されたが、アカウントやデバイスの識別子が同じである場合、保留中の暗号化状態の復元メタデータがないか兄弟関係にある token-hash ストレージルートをスキャン。
次回の Matrix 起動時に、バックアップされたルームキーを新しい crypto store へ復元。

スナップショットに関する詳細は以下の通りです。

スナップショットが成功すると、OpenClaw は ~/.openclaw/matrix/migration-snapshot.json にマーカーファイルを書き込みます。これにより、後の起動や修復パスで同じアーカイブを再利用できるようになります。
これらの自動移行スナップショットは、設定と状態のみをバックアップします（includeWorkspace: false）。
userId や accessToken がまだ不足しているなど、Matrix の移行状態が警告のみで実行可能なアクションがない場合、OpenClaw はまだスナップショットを作成しません。
スナップショットの作成ステップに失敗した場合、OpenClaw はリカバリポイントがない状態でデータを変更することを避けるため、その回の Matrix 移行をスキップします。

マルチアカウントのアップグレードについて：

最も古いフラットな Matrix ストア（~/.openclaw/matrix/bot-storage.json および ~/.openclaw/matrix/crypto/）は単一ストアの構成であったため、OpenClaw はこれを 1 つの特定された Matrix ターゲットアカウントにのみ移行できます。
すでにアカウントごとに分かれているレガシーな Matrix ストアは、設定された Matrix アカウントごとに検出され、準備されます。

自動で行われない移行内容

以前のパブリックな Matrix plugin では、Matrix ルームキーのバックアップは自動的に作成されていませんでした。ローカルの暗号化状態は保存され、デバイスの検証も要求されましたが、ルームキーが homeserver にバックアップされていることは保証されていませんでした。

そのため、暗号化を使用しているインストール環境では、移行が部分的になる可能性があります。

OpenClaw は以下の項目を自動的に復旧することはできません。

バックアップされたことのない、ローカルのみに存在するルームキー。
homeserver、userId、または accessToken がまだ利用できず、ターゲットの Matrix アカウントを特定できない場合の暗号化状態。
複数の Matrix アカウントが設定されているが channels.matrix.defaultAccount が設定されていない場合の、1 つの共有フラット Matrix ストアの自動移行。
標準の Matrix パッケージではなく、リポジトリのパスに固定されているカスタムプラグインパスでのインストール。
古いストアにバックアップされたキーはあったが、復号キーをローカルに保持していなかった場合の、不足しているリカバリキー。

現在の警告の対象：

カスタムの Matrix プラグインパスによるインストールは、Gateway の起動時と openclaw doctor の両方で通知されます。

古いインストール環境において、バックアップされていないローカルのみの暗号化履歴があった場合、アップグレード後も一部の古い暗号化メッセージが読み取れないままになる可能性があります。

推奨されるアップグレード手順

OpenClaw と Matrix plugin を通常通り更新します。起動時に Matrix の移行をすぐに完了させるため、--no-restart を付けない通常の openclaw update を実行するのがおすすめです。
次のコマンドを実行します：
Terminal window
```
openclaw doctor --fix
```
Matrix の移行作業が必要な場合、doctor はまず移行前のスナップショットを作成（または再利用）し、アーカイブのパスを表示します。
Gateway を起動または再起動します。
現在の認証状態とバックアップの状態を確認します：
Terminal window
```
openclaw matrix verify status
openclaw matrix verify backup status
```
OpenClaw からリカバリーキーが必要だと表示された場合は、次を実行してください：
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
```
サーバー側にキーのバックアップがまだ存在しない場合は、将来の復旧に備えて新しく作成します：
Terminal window
```
openclaw matrix verify bootstrap
```

暗号化データの移行の仕組み

暗号化データの移行は、2つのステージで行われます：

起動時または openclaw doctor --fix の実行時に、暗号化データの移行が必要であれば、移行前のスナップショットを作成または再利用します。
起動時または openclaw doctor --fix が、現在インストールされている Matrix plugin を通じて古い Matrix crypto store を調査します。
バックアップの復号キーが見つかった場合、OpenClaw はそれを新しいリカバリーキーのフローに書き込み、ルームキーの復元を保留状態としてマークします。
次回の Matrix 起動時に、OpenClaw はバックアップされたルームキーを新しい crypto store へ自動的に復元します。

もし古いストアにバックアップされていないルームキーがある場合、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 ストアを見つけましたが、どのアカウントに割り当てるべきか判断できません。
対処法：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 ストアを見つけましたが、どのアカウントに割り当てるべきか判断できません。
対処法：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 の状態を検出しましたが、識別情報や認証データが不足しているため、移行がブロックされています。
対処法：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 クライアント側のフォールバック処理で古いストレージが見つかりましたが、移動に失敗しました。OpenClaw は、不完全な状態で新しいストアを開始するのを避けるため、処理を中断しました。
対処法：ファイルシステムの権限や競合を確認し、古い状態を保持したままエラーを修正して再試行してください。

Matrix is installed from a custom path: ...

意味：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.json ファイルの自動的な上書きを拒否しました。
対処法：復元コマンドを再試行する前に、どちらのリカバリキーが正しいか確認してください。

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

意味：バックアップは存在しますが、このデバイスがクロス署名チェーンを十分に信頼していません。
対処法：openclaw matrix verify device "<your-recovery-key>" を再実行してください。

Matrix recovery key is required

意味：リカバリキーが必要なステップで、キーを指定せずに実行しようとしました。
対処法：リカバリキーを付与してコマンドを再実行してください。

Invalid Matrix recovery key: ...

意味：提供されたキーが解析できないか、期待される形式と一致しません。
対処法：Matrix クライアントまたはリカバリキーファイルから、正確なキーをコピーして再試行してください。

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.

意味：デバイスの検証が完了するまで、secret storage からバックアップキーを復元することはできません。
対処法：先に 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

もし実行後もデバイスが未検証（unverified）のままの場合は、Matrix クライアントから SAS 絵文字または 10 進数コードを比較して、一致することを確認し、検証を完了させてください。

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。