Matrix の移行

以前の公開 matrix Plugin から現在の実装にアップグレードします。

ほとんどのユーザーは、そのままアップグレードできます。

• Plugin は @openclaw/matrix のままです
• チャンネルは matrix のままです
• 設定は引き続き channels.matrix の下にあります
• キャッシュされた認証情報は共有 state/openclaw.sqlite Plugin 状態に移動します
• ランタイム状態は引き続き ~/.openclaw/matrix/ の下にあります

設定キーの名前を変更したり、新しい名前で Plugin を再インストールしたりする必要はありません。 ルートの openclaw パッケージには、Matrix ランタイムコードや Matrix SDK の依存関係がバンドルされなくなりました。openclaw channels status で Matrix が設定済みであるものの Plugin がインストールされていないと表示される場合は、openclaw doctor --fix または openclaw plugins install @openclaw/matrix を実行してください。Matrix SDK パッケージをルートの OpenClaw パッケージにインストールしないでください。

移行によって自動的に行われること

Matrix の移行は、openclaw doctor --fix を実行すると行われます。専用の Matrix ストアの隣にあるファイルベースのサイドカーでは、クライアント起動時のフォールバックが維持されますが、認証情報ファイルのインポートは Doctor でのみ行われます。ランタイムは正規の SQLite 認証情報状態のみを読み取ります。

Doctor の移行対象は次のとおりです。

• 廃止された ~/.openclaw/credentials/matrix/credentials*.json ファイルをアーカイブする前にインポートして検証する
• 同じアカウント選択と channels.matrix 設定を維持する
• ファイルベースのサイドカー状態（bot-storage.json 同期キャッシュ、recovery-key.json、legacy-crypto-migration.json、IndexedDB スナップショット）を Matrix SQLite 状態にインポートする。移行されたファイルは .migrated サフィックスを付けてアーカイブされます
• 後でアクセストークンが変更された場合に、同じ Matrix アカウント、ホームサーバー、ユーザー、デバイスについて、既存の最も完全なトークンハッシュストレージルートを再利用する

2026.4 より前の OpenClaw リリースからのアップグレード

2026.6 系までのリリースでは、元のフラットな単一ストアの Matrix レイアウト（~/.openclaw/matrix/bot-storage.json と ~/.openclaw/matrix/crypto/）も移行し、古い Rust 暗号化ストアから暗号化状態を復旧する準備を行っていました。現在のリリースには、その移行処理は含まれていません。

まだフラットレイアウトを使用しているインストール環境をアップグレードする場合は、まず 2026.6 リリースにアップグレードし、openclaw doctor --fix を実行して、Gateway を一度起動してください。これにより、フラットストアと復旧可能なルームキーが移行されます。その後、最新リリースに更新してください。

以前の公開 Matrix Plugin は、Matrix のルームキーバックアップを自動的には作成していませんでした。古いインストール環境に、バックアップされたことのないローカルのみの暗号化履歴があった場合、移行方法にかかわらず、アップグレード後も一部の古い暗号化メッセージを読み取れないことがあります。

推奨アップグレード手順

1. OpenClaw と Matrix Plugin を通常どおり更新します。

2. 次を実行します。

   openclaw doctor --fix

3. Gateway を起動または再起動します。

4. 現在の検証状態とバックアップ状態を確認します。

   openclaw matrix verify statusopenclaw matrix verify backup status

5. 修復する Matrix アカウントのリカバリーキーを、アカウント固有の環境変数に設定します。デフォルトアカウントが 1 つだけの場合は、MATRIX_RECOVERY_KEY で問題ありません。複数のアカウントがある場合は、アカウントごとに 1 つの変数（例: MATRIX_RECOVERY_KEY_ASSISTANT）を使用し、コマンドに --account assistant を追加します。

6. リカバリーキーが必要であると OpenClaw に表示された場合は、該当するアカウントに対して次のコマンドを実行します。

   printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdinprintf '%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-stdinprintf '%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 と入力します。コマンドは、Matrix ID が完全に信頼されるまで待機してから成功を報告します。

8. 復旧できない古い履歴を意図的に破棄し、今後のメッセージ用に新しいバックアップの基準状態を作成する場合は、次を実行します。

   openclaw matrix verify backup reset --yes

   古いリカバリーキーで新しいバックアップを解除できないようにする場合にのみ、--rotate-recovery-key を追加します。

9. サーバー側のキーバックアップがまだ存在しない場合は、今後の復旧用に作成します。

   openclaw matrix verify bootstrap

よくあるメッセージとその意味

Failed migrating legacy Matrix client storage: ...

• 意味: Matrix のクライアント側フォールバックでファイルベースのサイドカー状態が見つかりましたが、SQLite へのインポートに失敗しました。OpenClaw は、何も通知せずに新しいストアで起動するのではなく、完了した移動をロールバックして、そのフォールバックを中止します。
• 対処方法: ファイルシステムの権限や競合を調べ、古い状態をそのまま保持し、エラーを修正してから再試行します。

Matrix is installed from a custom path: ...

• 意味: Matrix がパスインストールに固定されているため、メインラインの更新ではデフォルトの Matrix パッケージに自動的に置き換えられません。
• 対処方法: デフォルトの Matrix Plugin に戻す場合は、openclaw plugins install @openclaw/matrix で再インストールします。

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

• 意味: Plugin のインストールレコードが、存在しなくなったローカルパスを指しています。
• 対処方法: openclaw plugins install @openclaw/matrix で再インストールするか、リポジトリのチェックアウトから実行している場合は openclaw plugins install ./path/to/local/matrix-plugin を使用します。openclaw doctor --fix を使用して、古い Matrix Plugin の参照を削除することもできます。

手動復旧メッセージ

このデバイスでルームキーのバックアップが正常でない場合、openclaw matrix verify status と openclaw matrix verify backup status は、Backup issue: 行と Next steps: のガイダンスを出力します。

その他の復旧エラー:

Matrix recovery key is required

• 意味: リカバリーキーが必要な復旧手順を、リカバリーキーを指定せずに実行しました。
• 対処方法: --recovery-key-stdin を指定してコマンドを再実行します。例: printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

Invalid Matrix recovery key: ...

• 意味: 指定されたキーを解析できなかったか、想定される形式と一致しませんでした。
• 対処方法: Matrix クライアントまたはリカバリーキーのエクスポートから取得した正確なリカバリーキーを使用して再試行します。

Matrix recovery key was applied, but this device still lacks full Matrix identity trust.

• 意味: リカバリーキーによって使用可能なバックアップデータを解除できましたが、Matrix はこのデバイスに対する完全なクロス署名 ID の信頼をまだ確立していません。コマンド出力で Recovery key accepted、Backup usable、Cross-signing verified、Device verified by owner を確認してください。
• 対処方法: openclaw matrix verify self を実行し、別の Matrix クライアントでリクエストを承認して SAS を比較し、一致する場合にのみ yes と入力します。現在のクロス署名 ID を意図的に置き換える場合にのみ、printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing を使用してください。

復旧できない古い暗号化履歴を失うことを受け入れる場合は、代わりに openclaw matrix verify backup reset --yes を使用して現在のバックアップの基準状態をリセットできます。保存されたバックアップシークレットが破損している場合、このリセットによってシークレットストレージも修復され、再起動後に新しいバックアップキーを正しく読み込めるようになります。

暗号化履歴がまだ戻らない場合

次の確認を順番に実行します。

openclaw matrix verify status --verboseopenclaw matrix verify backup status --verboseprintf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin --verbose

バックアップが正常に復元されても、一部の古いルームの履歴がまだ欠落している場合、それらの欠落したキーは以前の Plugin でバックアップされていなかった可能性があります。

今後のメッセージ用に新しく始める場合

復旧できない古い暗号化履歴を失うことを受け入れ、今後に向けたクリーンなバックアップの基準状態のみが必要な場合は、次のコマンドを順番に実行します。

openclaw matrix verify backup reset --yesopenclaw matrix verify backup status --verboseopenclaw matrix verify status

その後もデバイスが未検証の場合は、Matrix クライアントで SAS の絵文字または数字コードを比較し、一致することを確認して検証を完了します。

関連項目

• Matrix: チャンネルのセットアップと設定。
• Matrix プッシュルール: 通知のルーティング。
• Doctor: ヘルスチェックと自動移行のトリガー。
• 移行ガイド: すべての移行パス（マシン間の移動、システム間のインポート）。
• Plugins: Plugin のインストールと登録。