Technical reference
Database schemas
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.
This page is an index. The reference is documented on seven pages, one per reader job. Open the page that matches your task and stay there.
| Page | Read it when |
|---|---|
| Database layout | The two database roles, their on-disk paths, and the tables behind individual features. |
| Versioning contract | How schema versions are recorded, when a bump is required, and how updaters cross one. |
| Per-person and companion storage | Personal GitHub connections, personal model accounts, and Apple companion delivery journals. |
| Storage changes and release preflight | Preparing for another backend, the material-change review checkpoint, and openclaw database preflight. |
| Agent schema history | Per-agent database schema versions, their changes, and their first releases. |
| State schema history | Shared state database schema versions, their changes, and their first releases. |
| Integrity, troubleshooting, and recovery | Integrity checks, common database errors, and the supported downgrade recovery path. |
Related
- 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 migrationsopenclaw 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.
- Database layout
- Plugin state listing index
- Mentions Inbox
- ACP replay accounting
- Meeting transcript tables
meeting_transcript_sessionsmeeting_transcript_utterancesmeeting_transcript_summaries- Update run ledger
- Cloud repository workspaces
- Versioning contract
- Schema bumps and older updaters
- Profile-owned skill library
- Personal GitHub connections and publication
- Personal model accounts
- Apple companion delivery journals
- Preparing for another database backend
- Keep operations at the owning store
- Preserve the data and concurrency contracts
- Keep engine-specific capabilities owned
- Review checkpoint for material changes
- Preflight a target release
- Agent schema history
- Creator namespace migration
- Participant identity migration
- State schema history
- State schema 16
- State schema 15
- State schema 13
- State schema 11
- State schema 9
- Integrity checks
- Troubleshooting
- Why you cannot go back after updating to 2026.7.2
- The Gateway refuses to start with a newer schema version error
- A database is quarantined after integrity verification failed
- Downgrades are unsupported
- Example: state schema 13 to 12
- Example: state schema 12 to 11
- Example: state schema 11 to 10
- Example: state schema 10 to 9
- Example: state schema 9 to 8
- Example: state schema 7 to 6
- Example: agent schema 17 to 16
- Downgrade recovery
