OpenClaw Matrix 遷移指南：自動升級與資料修復

遷移會自動處理哪些部分

當 Gateway 啟動，或是當你執行 openclaw doctor --fix 時，OpenClaw 會嘗試自動修復舊的 Matrix 狀態。在任何會改寫磁碟狀態的 Matrix 遷移步驟執行前，OpenClaw 都會建立或重複使用一個專門的復原快照。

當你使用 openclaw update 時，觸發的機制取決於 OpenClaw 的安裝方式：

• 原始碼安裝：在更新流程中會執行 openclaw doctor --fix，然後預設重新啟動 Gateway。
• 套件管理器安裝：更新套件後，會執行非互動式的 doctor 檢查，接著依賴預設的 Gateway 重啟來完成 Matrix 遷移。
• 如果你使用 openclaw update --no-restart，由啟動觸發的 Matrix 遷移會延後，直到你之後執行 openclaw doctor --fix 並重啟 Gateway。

自動遷移涵蓋的範圍包括：

• 在 ~/Backups/openclaw-migrations/ 建立或重複使用遷移前的快照。
• 重複使用你快取的 Matrix 憑證。
• 保留相同的帳號選擇與 channels.matrix 設定。
• 將舊的扁平化（flat）Matrix 同步儲存區移至目前的帳號專屬位置。
• 當目標帳號可以安全解析時，將舊的扁平化 Matrix 加密儲存區移至目前的帳號專屬位置。
• 如果本地存在密鑰，從舊的 Rust 加密儲存區中提取先前儲存的 Matrix 房間密鑰備份解密密鑰。
• 當之後 Access Token 變更時，針對相同的 Matrix 帳號、homeserver 和使用者，重複使用最完整的現有 Token-hash 儲存根目錄。
• 當 Matrix Access Token 變更但帳號/裝置身分保持不變時，掃描同級的 Token-hash 儲存根目錄，尋找待處理的加密狀態還原元數據。
• 在下次 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 帳號進行準備。

遷移無法自動處理哪些部分

之前的公開 Matrix 插件不會自動建立 Matrix 房間密鑰備份。它雖然會保存本地加密狀態並要求裝置驗證，但並不保證你的房間密鑰有備份到 homeserver。

這代表某些加密安裝只能完成部分遷移。

OpenClaw 無法自動復原以下內容：

• 從未備份過、僅存在於本地的房間密鑰。
• 當目標 Matrix 帳號因 homeserver、userId 或 accessToken 仍不可用而無法解析時的加密狀態。
• 當設定了多個 Matrix 帳號但未設定 channels.matrix.defaultAccount 時，單一共享扁平化 Matrix 儲存區的自動遷移。
• 固定在特定 Repo 路徑而非標準 Matrix 套件的自定義插件路徑安裝。
• 當舊儲存區有備份密鑰但本地未保留解密密鑰時，遺失的復原密鑰（Recovery Key）。

目前的警告範圍：

• Gateway 啟動和 openclaw doctor 都會提示自定義 Matrix 插件路徑的安裝情況。

如果你舊的安裝環境中有從未備份過的本地加密歷史紀錄，升級後某些較舊的加密訊息可能仍然無法讀取。

建議的升級流程

1. 正常更新 OpenClaw 和 Matrix plugin。 建議直接使用 openclaw update 而不加 --no-restart，這樣啟動時就能立刻完成 Matrix 遷移。

2. 執行：

   openclaw doctor --fix

   如果 Matrix 有需要處理的遷移工作，doctor 會先建立或重複使用遷移前的 snapshot，並印出封存路徑。

3. 啟動或重啟 Gateway。

4. 檢查目前的驗證與備份狀態：

   openclaw matrix verify status
   openclaw matrix verify backup status

5. 如果 OpenClaw 提示你需要 recovery key，請執行：

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

6. 如果這台裝置還是顯示未驗證，請執行：

   openclaw matrix verify device "<your-recovery-key>"

7. 如果你打算放棄無法復原的舊訊息紀錄，並想為未來的訊息建立全新的備份基準，請執行：

   openclaw matrix verify backup reset --yes

8. 如果伺服器端還沒有金鑰備份，請為未來的復原建立一個：

   openclaw matrix verify bootstrap

加密遷移的運作原理

加密遷移是一個分為兩個階段的過程：

1. 如果有加密遷移需要處理，啟動程序或 openclaw doctor --fix 會建立或重複使用遷移前的 snapshot。
2. 啟動程序或 openclaw doctor --fix 會透過目前安裝的 Matrix plugin 檢查舊的 Matrix crypto store。
3. 如果找到了備份解密金鑰，OpenClaw 會將它寫入新的 recovery-key 流程中，並將 room-key 復原標記為待處理。
4. 在下一次 Matrix 啟動時，OpenClaw 會自動將備份的 room keys 復原到新的 crypto store 中。

如果舊的 store 回報了從未備份過的 room keys，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 (...) or 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 找到一個共享的舊版加密儲存庫，但它拒絕猜測應該由哪個具名的 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 狀態，但遷移仍因缺少身份或憑證資料而被阻擋。
• 該怎麼做：完成 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 plugin 載入輔助進入點。
• 該怎麼做：重新安裝或修復 Matrix plugin（執行 openclaw plugins install @openclaw/matrix，如果是從 repo checkout 的則執行 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 發現輔助檔案路徑超出了 plugin 根目錄或未通過 plugin 邊界檢查，因此拒絕匯入。
• 該怎麼做：從信任的路徑重新安裝 Matrix plugin，然後重新執行 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 client 端回退機制找到了舊的扁平儲存空間，但移動失敗。OpenClaw 現在會中止該回退，而不是靜默地啟動一個全新的儲存庫。
• 該怎麼做：檢查檔案系統權限或衝突，保持舊狀態完整，並在修復錯誤後重試。

Matrix is installed from a custom path: ...

• 意義：Matrix 是從自定義路徑安裝的，因此主線更新不會自動將其替換為 repo 的標準 Matrix 套件。
• 該怎麼做：當你想回到預設的 Matrix plugin 時，請使用 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 無法自動復原復原金鑰（recovery key）。
• 該怎麼做：執行 openclaw matrix verify backup restore --recovery-key "<你的復原金鑰>"。

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

• 意義：OpenClaw 找到了舊的加密儲存庫，但無法安全地檢查它以準備復原。
• 該怎麼做：重新執行 openclaw doctor --fix。如果問題重複出現，請保持舊狀態目錄完整，並使用另一個已驗證的 Matrix 用戶端加上 openclaw matrix verify backup restore --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: ...

• 意義：新的 plugin 嘗試復原，但 Matrix 回傳錯誤。
• 該怎麼做：執行 openclaw matrix verify backup status，如有需要，請使用 openclaw matrix verify backup restore --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 "<你的復原金鑰>"。

如果你接受遺失無法復原的舊加密歷史訊息，你可以改用 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 "<你的復原金鑰>"。

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 "<你的復原金鑰>"。

自定義 Plugin 安裝訊息

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

• 意義：你的 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
openclaw matrix verify backup restore --recovery-key "<your-recovery-key>" --verbose

如果備份復原成功，但某些舊聊天室仍缺少歷史訊息，那些遺失的金鑰很可能從未被之前的 plugin 備份過。

如果你想為未來的訊息重新開始

如果你接受失去那些無法復原的舊加密歷史紀錄，且只想為之後的訊息建立一個乾淨的備份基準，請依序執行以下命令：

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

如果執行完後裝置仍然顯示未驗證，請從你的 Matrix 用戶端完成驗證，比對 SAS 表情符號或數字代碼並確認它們一致。

相關頁面

• Matrix
• Doctor
• 遷移
• Plugins