資料庫結構描述

OpenClaw 將控制平面狀態儲存在全域 SQLite 資料庫中，並將每個代理程式的資料分別儲存在一個 SQLite 資料庫中。資料庫開啟時會向前執行結構遷移。較舊的 OpenClaw 組建會拒絕由較新結構寫入的資料庫。

資料庫配置

少數資料量大或具有特定生命週期的功能會使用專用 SQLite 儲存區，包括任務登錄資料與軌跡資料。

版本控管合約

每個資料庫會在兩處記錄其結構：

• PRAGMA user_version 是 SQLite 結構版本。
• 主要的 schema_meta 資料列會記錄 role、agent_id、schema_version 及 app_version。app_version 是最後寫入結構中繼資料的 OpenClaw 組建。

OpenClaw 開啟受支援的舊版資料庫時，會套用僅向前的遷移。若資料庫的 user_version 比執行中的組建更新，OpenClaw 會拒絕該資料庫並回報 newer schema version 錯誤。閘道會在啟動前檢查所有已登錄的資料庫。若套件或原始碼目標宣告支援的結構比磁碟上的資料庫更舊，openclaw update 也會拒絕該目標。在加入結構中繼資料前發布的目標套件無法進行預檢。

透過 npm 手動安裝 OpenClaw 會略過更新程式的防護。資料庫開啟檢查仍會拒絕不相容的組建。

代理程式結構歷程

版本 3 是未發布的開發步驟，已併入版本 4。

狀態結構歷程

完整性檢查

閘道預檢只會讀取結構標頭。對於不需要遷移的資料庫，速度較慢的完整掃描由背景驗證程式負責。 隔離決策只會儲存在專用的 openclaw-quarantine.sqlite 儲存區中，因此即使被隔離的資料庫損壞，這些決策仍會保留。驗證結果會寫入記錄。

疑難排解

為何更新至 2026.7.2 後無法退回舊版

截至 v2026.7.1 的每個版本都使用代理程式結構 1 與狀態結構 1。2026.7.2 發布系列（從 v2026.7.2-beta.1 開始）會在首次啟動時向前遷移你的資料庫。此遷移為單向操作：資料會改寫成較新的結構，之後安裝舊版 OpenClaw 並不會將其復原。較舊的組建會拒絕啟動，並顯示 newer schema version 錯誤，指出擁有該資料庫的組建。

降級二進位檔絕不會降級資料。若更新後必須執行早於 2026.7.2 的版本，你有三個選項：

1. 還原更新前建立的備份。在重大更新前先建立並驗證備份。
2. 讓較舊的組建使用獨立的狀態目錄（OPENCLAW_STATE_DIR）。它會以全新狀態啟動；你已遷移的資料會保持不變，供你日後返回較新組建時使用。
3. 依照下方的手動降級程序操作。此程序不受支援，若沒有經過驗證的備份，可能造成資料遺失。

自 2026.7.2 起，openclaw update 會拒絕安裝無法開啟目前資料庫的版本，因此更新程式不會讓你陷入這種情況。透過 npm 手動安裝舊版本會略過這項防護；資料庫仍會拒絕舊版二進位檔，但只會在安裝完成後才拒絕。

閘道因結構版本較新的錯誤而拒絕啟動

較新的 OpenClaw 組建曾寫入你的資料庫，而目前執行中的組建較舊。錯誤訊息及閘道啟動記錄會指出擁有該資料庫的組建（app_version）。請安裝該版本或更新版本，或使用上述任一選項。請勿編輯資料庫來消除錯誤。

資料庫在完整性驗證失敗後遭到隔離

背景驗證程式已證實檔案損毀，現在每次開啟都會立即失敗，而不再重新掃描。請從備份還原或修復資料庫，然後執行 openclaw doctor --fix 以清除隔離記錄。如果隔離記錄本身無法清除，Doctor 會回報明確錯誤；請重複執行，直到它回報狀態正常。

不支援降級

手動結構降級僅供願意承擔風險的代理程式與操作人員使用。編輯任何資料庫前，請先建立並驗證備份。停止閘道及所有可能開啟該資料庫的處理程序。

一般程序如下：

1. 閱讀目標版本的結構與遷移。
2. 在單一交易中，刪除目標版本之後加入的每個資料表、索引、觸發程序及資料行。
3. 將 PRAGMA user_version 與 schema_meta.schema_version 設為目標版本。
4. 啟動閘道前，執行目標版本的完整資料庫驗證。

範例：代理程式結構從 11 降至 9

結構 10 加入了作用中逐字記錄投影。結構 11 加入了租約、持久傳遞、對話位址狀態及心跳偵測結果。QMD 協調使用 state_leases 中的資料列；沒有需要保留的獨立 QMD 資料表。

檢查寫入資料庫的確切結構後，對每個受影響的每代理程式資料庫執行等效的 SQL：

BEGIN IMMEDIATE; DROP TABLE IF EXISTS heartbeat_outcomes;DROP TABLE IF EXISTS conversation_deliveries;DROP TABLE IF EXISTS state_leases;DROP TABLE IF EXISTS session_transcript_active_events; ALTER TABLE session_transcript_index_state DROP COLUMN active_event_count;ALTER TABLE session_transcript_index_state DROP COLUMN active_message_count;ALTER TABLE conversations DROP COLUMN delivery_target; PRAGMA user_version = 9;UPDATE schema_metaSET schema_version = 9,    updated_at = unixepoch('now') * 1000WHERE meta_key = 'primary'; COMMIT;

這會捨棄版本 10-11 的狀態，包括進行中的傳遞作業、租約、心跳偵測結果及衍生的作用中逐字記錄投影。若降級操作失敗，請從已驗證的備份還原。