データベーススキーマ

OpenClaw は、コントロールプレーンの状態をグローバル SQLite データベースに、エージェントデータをエージェントごとの SQLite データベースに保存します。データベースを開くと、スキーマ移行が前方へ実行されます。古い OpenClaw ビルドは、より新しいスキーマによって書き込まれたデータベースを拒否します。

データベース構成

タスクレジストリや軌跡データなど、大容量またはライフサイクル固有の一部の機能では、専用の SQLite ストアを使用します。

バージョニング契約

各データベースは、スキーマを次の 2 か所に記録します。

• PRAGMA user_version は SQLite スキーマバージョンです。
• プライマリ schema_meta 行には、role、agent_id、schema_version、および app_version が記録されます。app_version は、スキーマメタデータを最後に書き込んだ OpenClaw ビルドです。

OpenClaw は、サポート対象の古いデータベースを開くと、前方のみの移行を適用します。user_version が実行中のビルドより新しいデータベースは拒否され、newer schema version エラーが報告されます。Gateway は起動前に、登録されているすべてのデータベースを確認します。openclaw update は、宣言されたスキーマサポートがディスク上のデータベースより古いパッケージまたはソースターゲットも拒否します。スキーマメタデータが追加される前に公開されたターゲットパッケージは、事前検査できません。

npm を使用して OpenClaw を手動でインストールすると、アップデーターのガードが迂回されます。それでも、データベースを開く際のチェックにより、互換性のないビルドは拒否されます。

エージェントスキーマの履歴

バージョン 3 は、出荷されていない開発段階であり、バージョン 4 に統合されました。

状態スキーマの履歴

整合性チェック

Gateway の事前検査では、スキーマヘッダーのみを読み取ります。移行が不要なデータベースに対する低速な完全スキャンは、バックグラウンド検証機能が担当します。 隔離の決定は専用の 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 より古いリリースを実行する必要がある場合は、次の 3 つの選択肢があります。

1. 更新前に取得したバックアップを復元します。メジャーアップデートの前にバックアップを作成して検証してください。
2. 別の状態ディレクトリ（OPENCLAW_STATE_DIR）を指定して古いビルドを実行します。新規状態で起動し、移行済みデータは新しいビルドに戻るときのために変更されずに残ります。
3. 以下の手動ダウングレード手順に従います。これはサポート対象外であり、検証済みバックアップがない場合はデータ損失の危険があります。

2026.7.2 以降、openclaw update は現在のデータベースを開けないリリースのインストールを拒否するため、アップデーターによってこの状況に陥ることはありません。npm を使用して古いバージョンを手動でインストールすると、このガードが迂回されます。その場合もデータベースは古いバイナリを拒否しますが、拒否されるのはインストール後です。

新しいスキーマバージョンのエラーにより Gateway が起動を拒否する

より新しい OpenClaw ビルドがデータベースに書き込み、実行中のビルドがそれより古い状態です。エラーと Gateway の起動ログには、データベースを所有するビルド（app_version）が示されます。そのバージョン以降をインストールするか、上記のいずれかの選択肢を使用してください。エラーを抑止する目的でデータベースを編集しないでください。

整合性検証の失敗後にデータベースが隔離される

バックグラウンド検証機能によってファイルの破損が確認されており、開くたびに再スキャンせず即座に失敗するようになります。バックアップからデータベースを復元するか修復してから、openclaw doctor --fix を実行して隔離レコードを消去してください。隔離レコード自体を消去できない場合、Doctor は明示的なエラーを報告します。正常と報告されるまで再実行してください。

ダウングレードはサポート対象外

手動でのスキーマダウングレードは、リスクを受け入れるエージェントおよびオペレーター向けです。データベースを編集する前に、バックアップを作成して検証してください。Gateway と、データベースを開く可能性のあるすべてのプロセスを停止します。

一般的な手順は次のとおりです。

1. 対象リリースのスキーマと移行を確認します。
2. 1 つのトランザクション内で、対象バージョンより後に導入されたすべてのテーブル、インデックス、トリガー、およびカラムを削除します。
3. PRAGMA user_version と schema_meta.schema_version を対象バージョンに設定します。
4. Gateway を起動する前に、対象リリースの完全なデータベース検証を実行します。

例：エージェントスキーマ 11 から 9

スキーマ 10 では、アクティブトランスクリプトのプロジェクションが追加されました。スキーマ 11 では、リース、永続的配信、会話アドレス状態、および Heartbeat の結果が追加されました。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;

これにより、処理中の配信操作、リース、Heartbeat の結果、および派生したアクティブトランスクリプトのプロジェクションを含む、バージョン 10～11 の状態が破棄されます。ダウングレードに失敗した場合は、検証済みバックアップから復元してください。