Database schemas

Database schemas 문서는 OpenClaw 공식 문서(reference/database-schemas)를 한국어로 정리한 가이드입니다. OpenClaw SQLite database locations, schema versions, integrity checks, and downgrade recovery 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

OpenClaw SQLite database locations, schema versions, integrity checks, and downgrade recovery

한국어 가이드 범위: reference/database-schemas 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Database layout
Versioning contract
Agent schema history
State schema history
Integrity checks
트러블슈팅
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: agent schema 11 to 9

상세 내용

본문

OpenClaw stores control-plane state in a global SQLite 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.

Database layout

A few high-volume or lifecycle-specific features use dedicated SQLite stores, including the task registry and trajectory data.

Scope	Default path	Contents
Global control plane	`~/.openclaw/state/openclaw.sqlite`	Shared configuration state, registries, approvals, plugin state, and shared runtime state
Per-agent data plane	`~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`	Sessions, transcripts, memory indexes, auth state, conversation state, and agent-scoped runtime state

Versioning contract

Each database records its schema in two places:

주요 항목:

PRAGMA user_version is the SQLite schema version.
The primary schema_meta row records role, agent_id, schema_version, and app_version. app_version is the OpenClaw build that last wrote the schema metadata.

Agent schema history

Version 3 was an unshipped development step folded into version 4.

Version	Change	First release
1	Initial per-agent store (#88349)	`v2026.5.30-beta.1`, stable through `v2026.7.1`
2	Memory index identity (#104449)	`v2026.7.2-beta.1`
4	Sessions and transcripts moved into SQLite (#98236)	`v2026.7.2-beta.1`
5-6	Terminal freshness and state lifecycle (#104859)	`v2026.7.2-beta.1`
7	Per-entry lifecycle status projection (#106151)	`v2026.7.2-beta.1`
8	Per-transcript session provenance (#106766)	`v2026.7.2-beta.2`
9	`STRICT` tables (#108663)	`v2026.7.2-beta.2`
10	Materialized active transcript paths (#108851)	Unreleased
11	Leases, durable delivery, conversation addresses, and heartbeat outcomes (#109636, #95838, #109999)	Unreleased

State schema history

Version	Change	First release
1	Initial shared state database	`v2026.5.30-beta.1`
2	Metadata-only message audit events (#103903)	`v2026.7.2-beta.1`
3	`STRICT` tables and schema-drift hardening (#108663)	`v2026.7.2-beta.2`
4	Session watch provenance replaces encoded sentinel rows	Unreleased

Integrity checks

The Gateway preflight reads schema headers only. The background verifier owns the slower full scan for databases that do not need migration. Quarantine decisions live only in a dedicated openclaw-quarantine.sqlite store, so they survive damage to the databases being quarantined. Verification results are logged.

When	Check
Every open	Validate the `schema_meta` table and primary metadata row
Before a pending migration	Run a full integrity, foreign-key, role, schema, and index scan
Gateway background verifier	Run the full scan about once daily and log results
Doctor, backup verification, and compaction	Run the full scan before accepting or rewriting the database

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

Why you cannot go back after updating to 2026.7.2

Every release through v2026.7.1 used agent schema 1 and state schema 1. The 2026.7.2 release train (starting with v2026.7.2-beta.1) migrates your databases forward on first start. That migration is one-way: the data is rewritten into the newer schema, and installing an older OpenClaw afterwards does not undo it. The older build refuses to start with a newer schema version error that names the build that owns the database.

The Gateway refuses to start with a newer schema version error

A newer OpenClaw build wrote your databases, and the running build is older. The error and the Gateway startup log name the build that owns the database (app_version). Install that version or newer, or use one of the options above. Do not edit the database to silence the error.

A database is quarantined after integrity verification failed

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

Downgrades are unsupported

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

Example: agent schema 11 to 9

Schema 10 added the active transcript projection. Schema 11 added leases, durable delivery, conversation-address state, and heartbeat outcomes. QMD coordination uses rows in state_leases; there is no separate QMD table to preserve.

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;

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/database-schemas
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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;

Database schemas

핵심 요약

OpenClaw SQLite database locations, schema versions, integrity checks, and downgrade recovery

한국어 가이드 범위: reference/database-schemas 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Database layout
Versioning contract
Agent schema history
State schema history
Integrity checks
트러블슈팅
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: agent schema 11 to 9

상세 내용

본문

Database layout

A few high-volume or lifecycle-specific features use dedicated SQLite stores, including the task registry and trajectory data.

Scope	Default path	Contents
Global control plane	`~/.openclaw/state/openclaw.sqlite`	Shared configuration state, registries, approvals, plugin state, and shared runtime state
Per-agent data plane	`~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`	Sessions, transcripts, memory indexes, auth state, conversation state, and agent-scoped runtime state

Versioning contract

Each database records its schema in two places:

주요 항목:

PRAGMA user_version is the SQLite schema version.
The primary schema_meta row records role, agent_id, schema_version, and app_version. app_version is the OpenClaw build that last wrote the schema metadata.

Agent schema history

Version 3 was an unshipped development step folded into version 4.

Version	Change	First release
1	Initial per-agent store (#88349)	`v2026.5.30-beta.1`, stable through `v2026.7.1`
2	Memory index identity (#104449)	`v2026.7.2-beta.1`
4	Sessions and transcripts moved into SQLite (#98236)	`v2026.7.2-beta.1`
5-6	Terminal freshness and state lifecycle (#104859)	`v2026.7.2-beta.1`
7	Per-entry lifecycle status projection (#106151)	`v2026.7.2-beta.1`
8	Per-transcript session provenance (#106766)	`v2026.7.2-beta.2`
9	`STRICT` tables (#108663)	`v2026.7.2-beta.2`
10	Materialized active transcript paths (#108851)	Unreleased
11	Leases, durable delivery, conversation addresses, and heartbeat outcomes (#109636, #95838, #109999)	Unreleased

State schema history

Version	Change	First release
1	Initial shared state database	`v2026.5.30-beta.1`
2	Metadata-only message audit events (#103903)	`v2026.7.2-beta.1`
3	`STRICT` tables and schema-drift hardening (#108663)	`v2026.7.2-beta.2`
4	Session watch provenance replaces encoded sentinel rows	Unreleased

Integrity checks

When	Check
Every open	Validate the `schema_meta` table and primary metadata row
Before a pending migration	Run a full integrity, foreign-key, role, schema, and index scan
Gateway background verifier	Run the full scan about once daily and log results
Doctor, backup verification, and compaction	Run the full scan before accepting or rewriting the database

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

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

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

Example: agent schema 11 to 9

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;

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/database-schemas
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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;

Database schemas

핵심 요약

문서 구성

상세 내용

본문

Database layout

Versioning contract

Agent schema history

State schema history

Integrity checks

트러블슈팅

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: agent schema 11 to 9

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Database schemas

핵심 요약

문서 구성

상세 내용

본문

Database layout

Versioning contract

Agent schema history

State schema history

Integrity checks

트러블슈팅

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: agent schema 11 to 9

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드