Datenbankschemata

OpenClaw speichert den Zustand der Steuerungsebene in einer globalen SQLite-Datenbank und Agentendaten in jeweils einer SQLite-Datenbank pro Agent. Schemamigrationen werden beim Öffnen einer Datenbank vorwärts ausgeführt. Ältere OpenClaw-Builds verweigern Datenbanken, die mit einem neueren Schema geschrieben wurden.

Datenbanklayout

Einige Funktionen mit hohem Datenaufkommen oder spezifischem Lebenszyklus verwenden dedizierte SQLite-Speicher, darunter die Aufgabenregistrierung und Trajektoriendaten.

Versionierungsvertrag

Jede Datenbank zeichnet ihr Schema an zwei Stellen auf:

• PRAGMA user_version ist die SQLite-Schemaversion.
• Die primäre schema_meta-Zeile zeichnet role, agent_id, schema_version und app_version auf. app_version ist der OpenClaw-Build, der die Schemametadaten zuletzt geschrieben hat.

OpenClaw wendet beim Öffnen einer älteren unterstützten Datenbank ausschließlich Vorwärtsmigrationen an. Es verweigert eine Datenbank, deren user_version neuer als der ausgeführte Build ist, und meldet einen newer schema version-Fehler. Der Gateway prüft vor dem Start alle registrierten Datenbanken. openclaw update verweigert außerdem ein Paket- oder Quellziel, dessen deklarierte Schemaunterstützung älter als eine auf dem Datenträger vorhandene Datenbank ist. Zielpakete, die vor Einführung der Schemametadaten veröffentlicht wurden, können nicht vorab geprüft werden.

Die manuelle Installation von OpenClaw über npm umgeht die Schutzprüfung des Aktualisierungsprogramms. Die Prüfungen beim Öffnen der Datenbank verweigern einen inkompatiblen Build weiterhin.

Verlauf des Agentenschemas

Version 3 war ein nicht ausgelieferter Entwicklungsschritt, der in Version 4 integriert wurde.

Verlauf des Zustandsschemas

Integritätsprüfungen

Die Vorabprüfung des Gateways liest nur Schemaheader. Der Hintergrundprüfer ist für die langsamere vollständige Prüfung von Datenbanken zuständig, die keine Migration benötigen. Quarantäneentscheidungen befinden sich ausschließlich in einem dedizierten openclaw-quarantine.sqlite-Speicher, sodass sie Beschädigungen der unter Quarantäne gestellten Datenbanken überdauern. Prüfungsergebnisse werden protokolliert.

Fehlerbehebung

Warum Sie nach der Aktualisierung auf 2026.7.2 nicht zurückkehren können

Jede Version bis einschließlich v2026.7.1 verwendete Agentenschema 1 und Zustandsschema 1. Die Versionsreihe 2026.7.2 (beginnend mit v2026.7.2-beta.1) migriert Ihre Datenbanken beim ersten Start vorwärts. Diese Migration ist unumkehrbar: Die Daten werden in das neuere Schema umgeschrieben, und die anschließende Installation einer älteren OpenClaw-Version macht dies nicht rückgängig. Der ältere Build verweigert den Start mit einem newer schema version-Fehler, der den Build nennt, dem die Datenbank gehört.

Ein Downgrade der Binärdatei führt niemals zu einem Downgrade der Daten. Wenn Sie nach der Aktualisierung eine Version vor 2026.7.2 ausführen müssen, haben Sie drei Möglichkeiten:

1. Stellen Sie eine vor der Aktualisierung erstellte Sicherung wieder her. Erstellen und überprüfen Sie Sicherungen vor größeren Aktualisierungen.
2. Führen Sie den älteren Build mit einem separaten Zustandsverzeichnis (OPENCLAW_STATE_DIR) aus. Er startet mit einem neuen Zustand; Ihre migrierten Daten bleiben unberührt, bis Sie zum neueren Build zurückkehren.
3. Befolgen Sie das nachstehende Verfahren für ein manuelles Downgrade. Es wird nicht unterstützt und birgt ohne überprüfte Sicherung das Risiko eines Datenverlusts.

Seit 2026.7.2 verweigert openclaw update die Installation einer Version, die Ihre aktuellen Datenbanken nicht öffnen kann, sodass das Aktualisierungsprogramm Sie nicht in diese Situation bringt. Die manuelle Installation einer älteren Version über npm umgeht diese Schutzprüfung; die Datenbanken verweigern die alte Binärdatei weiterhin, jedoch erst nach deren Installation.

Der Gateway verweigert den Start wegen eines Fehlers aufgrund einer neueren Schemaversion

Ein neuerer OpenClaw-Build hat Ihre Datenbanken geschrieben, und der ausgeführte Build ist älter. Der Fehler und das Startprotokoll des Gateways nennen den Build, dem die Datenbank gehört (app_version). Installieren Sie diese oder eine neuere Version oder verwenden Sie eine der oben genannten Optionen. Bearbeiten Sie die Datenbank nicht, um den Fehler zu unterdrücken.

Eine Datenbank wird nach einer fehlgeschlagenen Integritätsprüfung unter Quarantäne gestellt

Der Hintergrundprüfer hat nachgewiesen, dass die Datei beschädigt ist, und jeder Öffnungsversuch schlägt nun sofort fehl, statt eine erneute Prüfung auszuführen. Stellen Sie die Datenbank aus einer Sicherung wieder her oder reparieren Sie sie und führen Sie anschließend openclaw doctor --fix aus, um den Quarantäneeintrag zu löschen. Doctor meldet einen ausdrücklichen Fehler, wenn der Quarantäneeintrag selbst nicht gelöscht werden kann; führen Sie ihn erneut aus, bis er einen fehlerfreien Zustand meldet.

Downgrades werden nicht unterstützt

Manuelle Schemadowngrades sind für Agenten und Betreiber vorgesehen, die das Risiko akzeptieren. Erstellen und überprüfen Sie eine Sicherung, bevor Sie eine Datenbank bearbeiten. Beenden Sie den Gateway und jeden Prozess, der die Datenbank öffnen kann.

Das allgemeine Verfahren lautet:

1. Lesen Sie das Schema und die Migrationen der Zielversion.
2. Löschen Sie in einer Transaktion jede Tabelle, jeden Index, jeden Trigger und jede Spalte, die nach der Zielversion eingeführt wurden.
3. Setzen Sie PRAGMA user_version und schema_meta.schema_version auf die Zielversion.
4. Führen Sie die vollständige Datenbankprüfung der Zielversion aus, bevor Sie den Gateway starten.

Beispiel: Agentenschema 11 auf 9

Schema 10 fügte die Projektion aktiver Transkripte hinzu. Schema 11 fügte Leases, dauerhafte Zustellung, den Zustand von Konversationsadressen und Heartbeat-Ergebnisse hinzu. Die QMD-Koordination verwendet Zeilen in state_leases; es gibt keine separate QMD-Tabelle, die erhalten werden muss.

Führen Sie nach Prüfung des exakten Schemas, das die jeweilige Datenbank geschrieben hat, entsprechendes SQL für jede betroffene Datenbank pro Agent aus:

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;

Dadurch wird der Zustand der Versionen 10-11 verworfen, einschließlich laufender Zustellungsvorgänge, Leases, Heartbeat-Ergebnisse und der abgeleiteten Projektion aktiver Transkripte. Bei einem fehlerhaften Downgrade müssen Sie die überprüfte Sicherung wiederherstellen.