Datenbankschemas

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 lehnen Datenbanken ab, die mit einem neueren Schema geschrieben wurden.

Datenbankstruktur

Einige Funktionen mit hohem Datenvolumen oder einem spezifischen 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 lehnt eine Datenbank ab, 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 lehnt außerdem ein Paket- oder Quellziel ab, dessen deklarierte Schemaunterstützung älter als eine auf dem Datenträger vorhandene Datenbank ist. Für Zielpakete, die vor Einführung der Schemametadaten veröffentlicht wurden, kann keine Vorabprüfung durchgeführt werden.

Bei der manuellen Installation von OpenClaw über npm wird die Schutzprüfung des Updaters umgangen. Die Prüfungen beim Öffnen der Datenbank lehnen einen inkompatiblen Build dennoch ab.

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 ausschließlich 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 überstehen. Prüfungsergebnisse werden protokolliert.

Fehlerbehebung

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

Jede Veröffentlichung bis einschließlich v2026.7.1 verwendete Agentenschema 1 und Zustandsschema 1. Die Veröffentlichungsreihe 2026.7.2 (beginnend mit v2026.7.2-beta.1) migriert Ihre Datenbanken beim ersten Start vorwärts. Diese Migration erfolgt nur in eine Richtung: Die Daten werden in das neuere Schema umgeschrieben, und eine 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 für die Datenbank zuständigen Build nennt.

Ein Downgrade der Binärdatei führt niemals zu einem Downgrade der Daten. Wenn Sie nach der Aktualisierung eine Veröffentlichung 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 unangetastet, bis Sie zum neueren Build zurückkehren.
3. Befolgen Sie das nachstehende manuelle Downgrade-Verfahren. 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 Veröffentlichung, die Ihre aktuellen Datenbanken nicht öffnen kann. Der Updater versetzt Sie daher nicht in diese Situation. Die manuelle Installation einer älteren Version über npm umgeht diese Schutzprüfung; die Datenbanken lehnen die alte Binärdatei weiterhin ab, jedoch erst nach deren Installation.

Der Gateway verweigert den Start mit einem Fehler wegen 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 für die Datenbank zuständigen Build (app_version). Installieren Sie diese oder eine neuere Version oder verwenden Sie eine der oben genannten Möglichkeiten. Bearbeiten Sie die Datenbank nicht, um den Fehler zu unterdrücken.

Eine Datenbank wird unter Quarantäne gestellt, nachdem die Integritätsprüfung fehlgeschlagen ist

Der Hintergrundprüfer hat nachgewiesen, dass die Datei beschädigt ist, und jeder Öffnungsversuch schlägt nun sofort fehl, anstatt die Datei erneut zu prüfen. 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 expliziten Fehler, wenn der Quarantäneeintrag selbst nicht gelöscht werden kann; führen Sie den Befehl erneut aus, bis ein einwandfreier Zustand gemeldet wird.

Downgrades werden nicht unterstützt

Manuelle Schema-Downgrades 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 Zielveröffentlichung.
2. Entfernen Sie in einer Transaktion alle Tabellen, Indizes, Trigger und Spalten, 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 Zielveröffentlichung 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 beibehalten werden muss.

Führen Sie nach Prüfung des exakten Schemas, mit dem die jeweilige Datenbank geschrieben wurde, gleichwertiges 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.