--- read_when: - 新しいデータベーススキーマのエラーを診断する - アップデートまたはダウングレード前のデータベース互換性の確認 - 古い OpenClaw リリース向けのデータベースの復旧 summary: OpenClaw SQLite データベースの場所、スキーマバージョン、整合性チェック、ダウングレードからの復旧 title: データベーススキーマ x-i18n: generated_at: "2026-07-26T09:18:22Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 73993e2c593ba460784108aedef70bbfb499e525c709d6d6bdd956ccf93e0ddc source_path: reference/database-schemas.md workflow: 16 --- OpenClaw は、コントロールプレーンの状態をグローバル SQLite データベースに、エージェントデータをエージェントごとの SQLite データベースに保存します。データベースを開くと、スキーマ移行が前方へ実行されます。古い OpenClaw ビルドは、より新しいスキーマによって書き込まれたデータベースを拒否します。 ## データベース構成 | スコープ | デフォルトパス | 内容 | | -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | グローバルコントロールプレーン | `~/.openclaw/state/openclaw.sqlite` | 共有設定状態、レジストリ、承認、Plugin の状態、および共有ランタイム状態 | | エージェントごとのデータプレーン | `~/.openclaw/agents//agent/openclaw-agent.sqlite` | セッション、トランスクリプト、メモリインデックス、認証状態、会話状態、およびエージェントスコープのランタイム状態 | タスクレジストリや軌跡データなど、大容量またはライフサイクル固有の一部の機能では、専用の 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 を手動でインストールすると、アップデーターのガードが迂回されます。それでも、データベースを開く際のチェックにより、互換性のないビルドは拒否されます。 ## エージェントスキーマの履歴 | バージョン | 変更 | 最初のリリース | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | 1 | エージェントごとの初期ストア（[#88349](https://github.com/openclaw/openclaw/pull/88349)） | `v2026.5.30-beta.1`、`v2026.7.1` まで安定版 | | 2 | メモリインデックスの識別情報（[#104449](https://github.com/openclaw/openclaw/pull/104449)） | `v2026.7.2-beta.1` | | 4 | セッションとトランスクリプトを SQLite に移行（[#98236](https://github.com/openclaw/openclaw/pull/98236)） | `v2026.7.2-beta.1` | | 5-6 | ターミナルの鮮度と状態ライフサイクル（[#104859](https://github.com/openclaw/openclaw/pull/104859)） | `v2026.7.2-beta.1` | | 7 | エントリごとのライフサイクル状態プロジェクション（[#106151](https://github.com/openclaw/openclaw/pull/106151)） | `v2026.7.2-beta.1` | | 8 | トランスクリプトごとのセッション来歴（[#106766](https://github.com/openclaw/openclaw/pull/106766)） | `v2026.7.2-beta.2` | | 9 | `STRICT` テーブル（[#108663](https://github.com/openclaw/openclaw/pull/108663)） | `v2026.7.2-beta.2` | | 10 | 実体化されたアクティブトランスクリプトパス（[#108851](https://github.com/openclaw/openclaw/pull/108851)） | 未リリース | | 11 | リース、永続的配信、会話アドレス、および Heartbeat の結果（[#109636](https://github.com/openclaw/openclaw/pull/109636)、[#95838](https://github.com/openclaw/openclaw/pull/95838)、[#109999](https://github.com/openclaw/openclaw/pull/109999)） | 未リリース | バージョン 3 は、出荷されていない開発段階であり、バージョン 4 に統合されました。 ## 状態スキーマの履歴 | バージョン | 変更 | 最初のリリース | | ------- | -------------------------------------------------------------------------------------------------------- | ------------------- | | 1 | 初期共有状態データベース | `v2026.5.30-beta.1` | | 2 | メタデータのみのメッセージ監査イベント（[#103903](https://github.com/openclaw/openclaw/pull/103903)） | `v2026.7.2-beta.1` | | 3 | `STRICT` テーブルとスキーマドリフトの堅牢化（[#108663](https://github.com/openclaw/openclaw/pull/108663)） | `v2026.7.2-beta.2` | | 4 | エンコードされたセンチネル行をセッション監視の来歴に置換 | 未リリース | ## 整合性チェック | 実行時 | チェック内容 | | ------------------------------------------- | --------------------------------------------------------------- | | 開くたび | `schema_meta` テーブルとプライマリメタデータ行を検証 | | 保留中の移行前 | 完全な整合性、外部キー、ロール、スキーマ、およびインデックスのスキャンを実行 | | Gateway のバックグラウンド検証機能 | 完全スキャンを約 1 日に 1 回実行し、結果をログに記録 | | Doctor、バックアップ検証、および Compaction | データベースを受け入れるか書き換える前に完全スキャンを実行 | 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. 更新前に取得したバックアップを復元します。メジャーアップデートの前に[バックアップを作成して検証](/ja-JP/cli/backup)してください。 2. 別の状態ディレクトリ（`OPENCLAW_STATE_DIR`）を指定して古いビルドを実行します。新規状態で起動し、移行済みデータは新しいビルドに戻るときのために変更されずに残ります。 3. 以下の手動ダウングレード手順に従います。これはサポート対象外であり、検証済みバックアップがない場合はデータ損失の危険があります。 2026.7.2 以降、`openclaw update` は現在のデータベースを開けないリリースのインストールを拒否するため、アップデーターによってこの状況に陥ることはありません。npm を使用して古いバージョンを手動でインストールすると、このガードが迂回されます。その場合もデータベースは古いバイナリを拒否しますが、拒否されるのはインストール後です。 ### 新しいスキーマバージョンのエラーにより Gateway が起動を拒否する より新しい OpenClaw ビルドがデータベースに書き込み、実行中のビルドがそれより古い状態です。エラーと Gateway の起動ログには、データベースを所有するビルド（`app_version`）が示されます。そのバージョン以降をインストールするか、上記のいずれかの選択肢を使用してください。エラーを抑止する目的でデータベースを編集しないでください。 ### 整合性検証の失敗後にデータベースが隔離される バックグラウンド検証機能によってファイルの破損が確認されており、開くたびに再スキャンせず即座に失敗するようになります。バックアップからデータベースを復元するか修復してから、`openclaw doctor --fix` を実行して隔離レコードを消去してください。隔離レコード自体を消去できない場合、Doctor は明示的なエラーを報告します。正常と報告されるまで再実行してください。 ## ダウングレードはサポート対象外 手動でのスキーマダウングレードは、リスクを受け入れるエージェントおよびオペレーター向けです。データベースを編集する前に、[バックアップを作成して検証](/ja-JP/cli/backup)してください。Gateway と、データベースを開く可能性のあるすべてのプロセスを停止します。 一般的な手順は次のとおりです。 1. 対象リリースのスキーマと移行を確認します。 2. 1 つのトランザクション内で、対象バージョンより後に導入されたすべてのテーブル、インデックス、トリガー、およびカラムを削除します。 3. `PRAGMA user_version` と `schema_meta.schema_version` を対象バージョンに設定します。 4. Gateway を起動する前に、対象リリースの完全なデータベース検証を実行します。 ### 例：エージェントスキーマ 11 から 9 スキーマ 10 では、アクティブトランスクリプトのプロジェクションが追加されました。スキーマ 11 では、リース、永続的配信、会話アドレス状態、および Heartbeat の結果が追加されました。QMD の調整では `state_leases` 内の行を使用します。保持すべき独立した QMD テーブルはありません。 書き込みに使用された正確なスキーマを確認した後、影響を受けるエージェントごとの各データベースに対して、同等の SQL を実行します。 ```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_meta SET schema_version = 9, updated_at = unixepoch('now') * 1000 WHERE meta_key = 'primary'; COMMIT; ``` これにより、処理中の配信操作、リース、Heartbeat の結果、および派生したアクティブトランスクリプトのプロジェクションを含む、バージョン 10～11 の状態が破棄されます。ダウングレードに失敗した場合は、検証済みバックアップから復元してください。