Skip to main content
OpenClaw stores control-plane state in the shared state database and agent data in one SQLite database per agent. Schema migrations run forward when a database opens. Older OpenClaw builds refuse databases written by a newer schema. Two mechanisms back that contract. CI runs scripts/check-native-state-schema-version.mjs, which fails the build when the Swift and TypeScript state-database contracts declare different schema versions. openclaw doctor --fix owns file-to-SQLite migrations and records a receipt for each one in the shared migration_runs and migration_sources tables. Execution step receipts are separate from these persisted import receipts. A step blocked by an earlier refusal includes optional originatingRefusal fields stepId, code, and message naming the first failure. See legacy state migration for how to resolve it. This page is an index. The reference is documented on focused pages, one per reader job. Open the page that matches your task and stay there.
  • Backups — archives, per-database snapshots, scheduling, and offsite copies for the databases described here
  • Updating — updating safely, including the verified backup to take before a schema bump, and the rollback strategy
  • Doctor — the repair and migration tool that fixes stale config/state and reports health problems
  • openclaw doctor — CLI reference for the command that runs those migrations
  • openclaw update — CLI reference for the updater that preflights schema support

​
Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /reference/database-schemas#schema-bumps-and-older-updaters still resolves. Each entry points at the page that now holds the content.