OpenClaw SQLite Database Schemas, Locations, and Migration Guide

OpenClaw keeps control-plane state in a single global SQLite database, while each agent gets its own SQLite database for agent data. Schema migrations are applied forward whenever a database is opened. Older builds of OpenClaw will reject databases that were written by a newer schema version.

Database layout

Certain high-volume or lifecycle-specific features, such as the task registry and trajectory data, use their own dedicated SQLite stores.

Versioning contract

Each database records its schema in two locations:

• PRAGMA user_version holds the SQLite schema version.
• The primary schema_meta row stores role, agent_id, schema_version, and app_version. app_version identifies the OpenClaw build that last wrote the schema metadata.

Forward-only migrations are applied by OpenClaw when it opens an older supported database. If a database has a user_version newer than the running build, OpenClaw rejects it and reports a newer schema version error. Before startup, the Gateway checks every registered database. openclaw update also refuses a package or source target whose declared schema support is older than what the on-disk database requires. Target packages published before schema metadata was introduced cannot undergo preflight checks.

Manually installing OpenClaw through npm bypasses the updater guard. However, database open checks will still reject an incompatible build.

Agent schema history

Version 3 was a development iteration that never shipped and was merged into version 4.

State schema history

Integrity checks

Only schema headers are read during the Gateway preflight. The slower full scan is handled by the background verifier for databases that do not require migration. Quarantine decisions are stored exclusively in a dedicated openclaw-quarantine.sqlite store, so they remain intact even if the quarantined databases are damaged. Verification results are written to the log.

Troubleshooting

Why you cannot go back after updating to 2026.7.2

Agent schema 1 and state schema 1 were used by every release up to v2026.7.1. Starting with v2026.7.2-beta.1, the 2026.7.2 release train migrates your databases forward on first startup. This migration is irreversible: the data is rewritten to the newer schema, and installing an older OpenClaw afterward will not reverse it. The older build will refuse to start and will display a newer schema version error naming the build that owns the database.

Downgrading the binary never reverts the data. If you need to run a release older than 2026.7.2 after upgrading, you have three choices:

1. Restore a backup taken before the upgrade. Create and verify backups before major upgrades.
2. Point the older build at a separate state directory (OPENCLAW_STATE_DIR). It starts fresh, leaving your migrated data untouched for when you return to the newer build.
3. Use the manual downgrade procedure described below. This is unsupported and carries a risk of data loss without a verified backup.

Since 2026.7.2, openclaw update will not install a release that cannot open your current databases, so the updater will not put you in this position. Manually installing an older version through npm bypasses that guard; the databases still reject the old binary, but only after installation.

The Gateway refuses to start with a newer schema version error

Your databases were written by a newer OpenClaw build, and the running build is older. The error message and the Gateway startup log identify the build that owns the database (app_version). Install that version or a newer one, or use one of the options above. Do not edit the database to suppress the error.

A database is quarantined after integrity verification failed

The background verifier has confirmed the file is corrupt, and every open now fails immediately instead of rescanning. Restore the database from a backup or repair it, then run openclaw doctor --fix to remove the quarantine record. If the quarantine record itself cannot be cleared, Doctor reports an explicit error; rerun it until it reports clean.

Downgrades are unsupported

Manual schema downgrades are intended for agents and operators who accept the associated risks. Create and verify a backup before editing any database. Stop the Gateway and every process that can open the database.

The general procedure is:

1. Review the schema and migration files for the release you are targeting.
2. Within a single transaction, remove every table, index, trigger, and column that was added after the target version.
3. Assign the target version to both PRAGMA user_version and schema_meta.schema_version.
4. Execute the full database verification provided with the target release before the Gateway is started.

Example: agent schema 11 to 9

The active transcript projection was introduced in schema 10. Leases, durable delivery, conversation-address state, and heartbeat outcomes were added in schema 11. Rows inside state_leases are used for QMD coordination; no separate QMD table needs to be preserved.

After examining the exact schema that created it, run the equivalent SQL against each affected per-agent database:

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;

This operation discards state from versions 10 and 11, which includes in-flight delivery operations, leases, heartbeat outcomes, and the derived active transcript projection. If the downgrade fails, restore from the verified backup.