データベーススキーマ

​

データベース構成

​

バージョニング契約

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

​

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

​

状態スキーマの履歴

​

整合性チェック

​

トラブルシューティング

​

2026.7.2 への更新後に元に戻せない理由

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

​

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

​

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

​

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

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

​

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

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_meta
SET schema_version = 9,
    updated_at = unixepoch('now') * 1000
WHERE meta_key = 'primary';

COMMIT;