openclaw backup

為 OpenClaw 狀態、設定、驗證設定檔、頻道／提供者認證資訊、工作階段，以及選用的工作區建立本機備份封存檔。

openclaw backup createopenclaw backup create --output ~/Backupsopenclaw backup create --dry-run --jsonopenclaw backup create --verifyopenclaw backup create --no-include-workspaceopenclaw backup create --only-configopenclaw backup verify ./2026-03-09T08-00-00.000+08-00-openclaw-backup.tar.gzopenclaw backup sqlite create --global --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite create --agent main --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite list --repository ~/Backups/openclaw-sqliteopenclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id>openclaw backup sqlite verify ~/Backups/openclaw-sqlite/<snapshot-id> --scratch ~/Private/openclaw-scratchopenclaw backup sqlite restore ~/Backups/openclaw-sqlite/<snapshot-id> --target ./restored/openclaw.sqlite

注意事項

• 封存檔內嵌一份 manifest.json，其中包含解析後的來源路徑與封存配置。
• 預設輸出是在目前工作目錄中，以時間戳記命名的 .tar.gz 封存檔。時間戳記檔名使用你電腦的本地時區，並包含 UTC 偏移量。如果目前工作目錄位於要備份的來源樹狀目錄內，OpenClaw 會改用你的家目錄作為預設封存位置。
• 絕不覆寫既有的封存檔。為避免將輸出本身納入封存，位於來源狀態／工作區樹狀目錄內的輸出路徑會遭拒絕。
• openclaw backup verify <archive> 會檢查封存檔是否恰好包含一份根資訊清單、拒絕目錄周遊形式的封存路徑與 SQLite 附屬檔案、確認資訊清單宣告的每個承載內容都存在、驗證每個 SQLite 快照的檔案形式，並對標準 OpenClaw 資料庫執行完整的完整性與角色檢查。專用的外掛結構描述仍視為不透明內容，因為它們可能需要擁有者定義的 SQLite 功能。openclaw backup create --verify 會在寫入封存檔後立即執行該驗證。
• openclaw backup create --only-config 僅備份使用中的 JSON 設定檔。

SQLite 快照

當你需要針對單一 OpenClaw 擁有的 SQLite 資料庫建立可攜式成品，而非廣泛的狀態封存檔時，請使用 openclaw backup sqlite。

建立快照時，必須且只能指定一個具名來源：

儲存庫會為每個已提交的快照包含一個目錄。每個快照目錄恰好包含：

• manifest.json
• database.sqlite

建立快照時，會先驗證即時資料庫，再使用 SQLite VACUUM INTO 將已提交的 WAL 狀態擷取至精簡資料庫中，接著再次驗證產生的資料庫，最後在不覆寫既有路徑的情況下發布完成的目錄。全域快照會移除暫時性的傳遞佇列資料列並再次壓縮，避免已刪除的佇列承載內容留存在可用頁面中。

請勿將即時的 .sqlite、-wal、-shm 或 -journal 檔案複製為可攜式成品。僅複製已完成的快照目錄。

SQLite 快照可能包含驗證設定檔、工作階段狀態、外掛狀態及其他敏感記錄。請使用與即時 OpenClaw 狀態目錄相同的權限、加密、保留政策與目的地限制來保護儲存庫。

驗證與還原

openclaw backup sqlite verify <snapshot-directory>openclaw backup sqlite restore <snapshot-directory> --target <new-database-path>

驗證作業會檢查嚴格的資訊清單形式、成品大小與 SHA-256、SQLite 完整性、外部索引鍵、結構描述版本、資料庫角色與擁有者，以及 OpenClaw 擁有的索引定義。

驗證作業會驗證一份私密且內容固定的副本，因此路徑名稱競爭條件無法替換 SQLite 所檢查的位元組。依預設，該暫存副本會建立在快照儲存庫旁，並在命令返回前移除。預備根目錄及其祖先目錄鏈必須防止其他使用者替換該副本。POSIX 根目錄必須由目前使用者擁有，且群組與所有人皆不可寫入；若子目錄由使用者擁有，則可接受 /tmp 等具有黏著位元的祖先目錄。若 macOS ACL 授權會暴露預備區或使其可遭替換，便會遭拒絕。Windows 根目錄與祖先目錄必須由目前使用者或受信任的作業系統主體擁有，且 ACL 必須拒絕不受信任者存取預備區。對於唯讀掛載點或網路共用，請在具備同等加密與目的地控制的儲存空間上傳入 --scratch <existing-private-directory>。

建立快照時，也會在預備或發布資料庫位元組前，對儲存庫套用相同的擁有者、ACL、祖先目錄與路徑身分檢查。

還原作業會再次執行驗證，而且只會寫入全新的目標。它會拒絕既有目標、-wal、-shm 或 -journal 附屬檔案，且絕不會就地替換即時 OpenClaw 資料庫。目標父目錄須符合與驗證暫存空間相同的路徑安全需求。啟用已還原的資料庫仍須由操作人員明確地離線執行。

快照儲存庫是本機目錄。排程、上傳、保留、增量 WAL 套件、容錯移轉及開機時還原行為刻意不屬於此命令的範圍。

備份內容

openclaw backup create 會從你的本機 OpenClaw 安裝規劃來源：

• 狀態目錄（通常是 ~/.openclaw）
• 使用中的設定檔路徑
• 解析後的 credentials/ 目錄（當它存在於狀態目錄之外時）
• 從目前設定中探索到的工作區目錄，除非你傳入 --no-include-workspace

驗證設定檔與其他每個代理程式的執行階段狀態，皆存放在狀態目錄下的 SQLite 中（agents/<agentId>/agent/openclaw-agent.sqlite），因此狀態備份項目會自動涵蓋這些內容。

--only-config 會略過狀態、認證資訊目錄與工作區探索，並只封存使用中的設定檔路徑。

OpenClaw 會在建立封存檔前將路徑標準化：如果設定、認證資訊目錄或工作區已位於狀態目錄內，就不會將其重複列為個別的頂層備份來源。不存在的路徑會被略過。

建立封存檔期間，OpenClaw 會在 tar 讀取已知會即時變動的路徑前，先將其排除。這可避免檔案記錄大小與同時寫入之間產生競爭條件。篩選器會在每個備份的狀態目錄下套用下列相對於狀態目錄的規則：

這些規則不會篩選狀態目錄之外的工作區檔案。它們也會省略符合表格條件的已完成文字記錄與記錄檔，因此需要時請另行保留這些記錄。JSON 結果中的 skippedVolatileCount 會回報刻意省略的檔案數量。

狀態目錄下的 SQLite 資料庫會使用 VACUUM INTO 壓縮，避免已刪除頁面的殘留內容進入封存檔，且不會複製即時 WAL／SHM 檔案。如果某個由外掛擁有的資料庫需要無法取得、由擁有者定義的 SQLite 功能，作業會以封閉方式失敗，而不會退回原始頁面複製。透過工作區備份納入的 SQLite 檔案會當作工作區檔案複製，不受壓縮保證涵蓋。

狀態目錄的 extensions/ 樹狀目錄下，已安裝外掛的原始碼與資訊清單檔案會被納入，但其巢狀的 node_modules/ 相依性樹狀目錄會被略過，因為它們是可重新建置的安裝成品。還原封存檔後，如果已還原的外掛回報缺少相依性，請使用 openclaw plugins update <id>，或透過 openclaw plugins install <spec> --force 重新安裝。

無效設定行為

openclaw backup 會略過一般設定預檢，因此在復原期間仍可提供協助。工作區探索依賴有效的設定，因此若設定檔存在但無效，且工作區備份仍處於啟用狀態，openclaw backup create 會立即失敗。

若要在此情況下進行部分備份，請加上 --no-include-workspace 重新執行：它會繼續涵蓋狀態、設定與外部認證資訊目錄，同時完全略過工作區探索。

即使設定格式錯誤，--only-config 仍可運作，因為它不會為了探索工作區而剖析設定。

大小與效能

OpenClaw 不會強制執行內建的備份大小上限或單一檔案大小限制。實際限制取決於：

• 暫存封存檔寫入加上最終封存檔所需的可用空間
• 走訪大型工作區樹狀目錄並將其壓縮為 .tar.gz 所需的時間
• 使用 --verify 或 openclaw backup verify 重新掃描封存檔所需的時間
• 目的地檔案系統的行為：OpenClaw 優先使用不覆寫的硬連結發布步驟，並在不支援硬連結時退回獨佔複製

大型工作區通常是影響封存檔大小的主要因素。使用 --no-include-workspace 可建立較小且較快的備份，或使用 --only-config 建立最小的封存檔。

相關內容

• 命令列介面參考