English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Mainstream messaging

Matrix 遷移

從先前公開的 matrix Plugin 升級到目前的實作。

對大多數使用者而言，升級會就地完成：

  • Plugin 維持為 @openclaw/matrix
  • channel 維持為 matrix
  • 你的設定維持在 channels.matrix 底下
  • 快取的憑證維持在 ~/.openclaw/credentials/matrix/ 底下
  • 執行階段狀態維持在 ~/.openclaw/matrix/ 底下

你不需要重新命名設定鍵，或以新名稱重新安裝 Plugin。

遷移會自動執行的動作

當 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 設定
  • 將最舊的扁平 Matrix 同步儲存移至目前以帳號為範圍的位置
  • 在可安全解析目標帳號時，將最舊的扁平 Matrix 加密儲存移至目前以帳號為範圍的位置
  • 從舊的 rust 加密儲存中擷取先前儲存的 Matrix 房間金鑰備份解密金鑰，前提是該金鑰存在於本機
  • 當存取權杖稍後變更時，為相同 Matrix 帳號、homeserver 與使用者重用最完整的現有 token-hash 儲存根目錄
  • 當 Matrix 存取權杖變更但帳號/裝置身分維持相同時，掃描相鄰的 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 Plugin 不會自動建立 Matrix 房間金鑰備份。它會保留本機加密狀態並要求裝置驗證，但不保證你的房間金鑰已備份到 homeserver。

這表示部分加密安裝只能局部遷移。

OpenClaw 無法自動復原：

  • 從未備份的僅存在本機的房間金鑰
  • 因為 homeserver、userId 或 accessToken 仍不可用，導致目標 Matrix 帳號尚無法解析時的加密狀態
  • 已設定多個 Matrix 帳號但未設定 channels.matrix.defaultAccount 時，對單一共用扁平 Matrix 儲存的自動遷移
  • 固定到 repo 路徑、而非標準 Matrix 套件的自訂 Plugin 路徑安裝
  • 舊儲存有已備份金鑰，但未在本機保留解密金鑰時遺失的復原金鑰

目前警告範圍：

  • 自訂 Matrix Plugin 路徑安裝會同時由 Gateway 啟動與 openclaw doctor 顯示

如果你的舊安裝有從未備份的僅存在本機加密歷史紀錄，升級後某些較舊的加密訊息可能仍無法讀取。

建議升級流程

  1. 正常更新 OpenClaw 與 Matrix Plugin。 建議使用一般的 openclaw update，不要加上 --no-restart，讓啟動流程可以立即完成 Matrix 遷移。

  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 用戶端接受請求、比較 emoji 或十進位數字， 並且只有在相符時才輸入 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 會自動將已備份的房間金鑰還原到新的加密儲存中。

如果舊儲存回報有從未備份的房間金鑰，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 狀態存在，但 OpenClaw 無法將其對應到目前的 Matrix 帳號，因為尚未設定 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 (...)

  • 含義：新的以帳號為範圍的位置已經有同步或加密儲存，因此 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 找到一個共用的扁平舊版加密儲存，但拒絕猜測應由哪個具名 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 用戶端側備援機制發現舊的扁平儲存，但移動失敗。OpenClaw 現在會中止該備援流程，而不是靜默地以全新的儲存啟動。
  • 處理方式：檢查檔案系統權限或衝突，保持舊狀態完整，並在修正錯誤後重試。

Matrix is installed from a custom path: ...

  • 意義：Matrix 被固定為路徑安裝，因此主線更新不會自動將它替換成儲存庫的標準 Matrix 套件。
  • 處理方式：當你想回到預設 Matrix Plugin 時，請使用 openclaw plugins install @openclaw/matrix 重新安裝。

加密狀態復原訊息

matrix: restored X/Y room key(s) from legacy encrypted-state backup

  • 意義：已備份的房間金鑰已成功復原到新的加密儲存。
  • 處理方式：通常不需要做任何事。

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-stdin" after upgrade if they have the recovery key.

  • 意義：備份存在，但 OpenClaw 無法自動復原復原金鑰。
  • 處理方式：執行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin。

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

  • 意義：OpenClaw 找到了舊的加密儲存，但無法以足夠安全的方式檢查它來準備復原。
  • 處理方式：重新執行 openclaw doctor --fix。如果問題重複發生，請保持舊狀態目錄完整，並使用另一個已驗證的 Matrix 用戶端加上 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin 進行復原。

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，必要時再使用 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin 重試。

手動復原訊息

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，或設定 MATRIX_RECOVERY_KEY，必要時執行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify backup restore --recovery-key-stdin。

Store a recovery key with 'openclaw matrix verify device --recovery-key-stdin', then run 'openclaw matrix verify backup restore'.

  • 意義：此裝置目前未儲存復原金鑰。
  • 處理方式：設定 MATRIX_RECOVERY_KEY，執行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin，然後復原備份。

Backup key mismatch on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin' with the matching recovery key.

  • 意義：已儲存的金鑰與作用中的 Matrix 備份不相符。
  • 處理方式：將 MATRIX_RECOVERY_KEY 設為正確的金鑰，並執行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

如果你接受遺失無法復原的舊加密歷史，也可以改用 openclaw matrix verify backup reset --yes 重設目前的備份基準。當已儲存的備份密鑰損壞時，該重設也可能重新建立密鑰儲存，讓新的備份金鑰在重新啟動後能正確載入。

Backup trust chain is not verified on this device. Re-run 'openclaw matrix verify device --recovery-key-stdin'.

  • 意義：備份存在，但此裝置尚未充分信任交叉簽署信任鏈。
  • 處理方式：設定 MATRIX_RECOVERY_KEY，並執行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

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 用戶端或 recovery-key 檔案中的確切復原金鑰重試。

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

  • 意義：OpenClaw 可以套用復原金鑰，但 Matrix 仍尚未為此裝置建立完整的交叉簽署身分信任。檢查命令輸出中是否有 Recovery key accepted、Backup usable、Cross-signing verified 和 Device verified by owner。
  • 處理方式：執行 openclaw matrix verify self，在另一個 Matrix 用戶端中接受要求，比對 SAS，並且只有在相符時才輸入 yes。該命令會等待完整的 Matrix 身分信任建立完成後才回報成功。只有在你有意替換目前的交叉簽署身分時，才使用 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify bootstrap --recovery-key-stdin --force-reset-cross-signing。

Matrix key backup is not active on this device after loading from 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 --recovery-key-stdin' first.

  • 意義：此裝置必須先完成裝置驗證，才能從密鑰儲存復原。
  • 處理方式：先執行 printf '%s\n' "$MATRIX_RECOVERY_KEY" | openclaw matrix verify device --recovery-key-stdin。

自訂 Plugin 安裝訊息

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

  • 意義：你的 Plugin 安裝記錄指向一個已不存在的本機路徑。
  • 處理方式：使用 openclaw plugins install @openclaw/matrix 重新安裝；或者如果你是從儲存庫 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

如果備份成功復原，但部分舊房間仍缺少歷史，這些遺失的金鑰很可能從未被先前的 Plugin 備份。

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

如果你接受遺失無法復原的舊加密歷史，只想為後續建立乾淨的備份基準，請依序執行這些命令：

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

如果裝置之後仍未驗證，請從你的 Matrix 用戶端完成驗證：比對 SAS 表情符號或十進位代碼，並確認它們相符。

相關