Skema basis data

OpenClaw menyimpan status bidang kontrol dalam basis data SQLite global dan data agen dalam satu basis data SQLite per agen. Migrasi skema dijalankan maju saat basis data dibuka. Build OpenClaw lama menolak basis data yang ditulis oleh skema yang lebih baru.

Tata letak basis data

Beberapa fitur bervolume tinggi atau khusus siklus hidup menggunakan penyimpanan SQLite khusus, termasuk registri tugas dan data lintasan.

Kontrak pembuatan versi

Setiap basis data mencatat skemanya di dua tempat:

• PRAGMA user_version adalah versi skema SQLite.
• Baris schema_meta utama mencatat role, agent_id, schema_version, dan app_version. app_version adalah build OpenClaw yang terakhir menulis metadata skema.

OpenClaw menerapkan migrasi hanya-maju saat membuka basis data lama yang didukung. OpenClaw menolak basis data yang user_version-nya lebih baru daripada build yang berjalan dan melaporkan galat newer schema version. Gateway memeriksa semua basis data terdaftar sebelum dimulai. openclaw update juga menolak paket atau target sumber yang dukungan skemanya dinyatakan lebih lama daripada basis data pada disk. Paket target yang diterbitkan sebelum metadata skema ditambahkan tidak dapat diperiksa sebelumnya.

Menginstal OpenClaw secara manual melalui npm melewati pengaman pemutakhiran. Pemeriksaan saat membuka basis data tetap menolak build yang tidak kompatibel.

Riwayat skema agen

Versi 3 adalah tahap pengembangan yang tidak pernah dirilis dan digabungkan ke dalam versi 4.

Riwayat skema status

Pemeriksaan integritas

Pemeriksaan awal Gateway hanya membaca header skema. Pemverifikasi latar belakang menangani pemindaian lengkap yang lebih lambat untuk basis data yang tidak memerlukan migrasi. Keputusan karantina hanya disimpan dalam penyimpanan openclaw-quarantine.sqlite khusus, sehingga tetap bertahan meskipun basis data yang dikarantina rusak. Hasil verifikasi dicatat.

Pemecahan masalah

Mengapa Anda tidak dapat kembali setelah memperbarui ke 2026.7.2

Setiap rilis hingga v2026.7.1 menggunakan skema agen 1 dan skema status 1. Rangkaian rilis 2026.7.2 (dimulai dengan v2026.7.2-beta.1) memigrasikan basis data Anda ke versi yang lebih baru saat pertama kali dimulai. Migrasi tersebut bersifat satu arah: data ditulis ulang ke skema yang lebih baru, dan menginstal OpenClaw yang lebih lama setelahnya tidak membatalkannya. Build lama menolak untuk dimulai dengan galat newer schema version yang menyebutkan build pemilik basis data.

Menurunkan versi biner tidak pernah menurunkan versi data. Jika Anda harus menjalankan rilis yang lebih lama daripada 2026.7.2 setelah memperbarui, tersedia tiga opsi:

1. Pulihkan cadangan yang dibuat sebelum pemutakhiran. Buat dan verifikasi cadangan sebelum pemutakhiran besar.
2. Jalankan build lama dengan direktori status terpisah (OPENCLAW_STATE_DIR). Build tersebut dimulai dari awal; data Anda yang telah dimigrasikan tetap tidak tersentuh saat Anda kembali ke build yang lebih baru.
3. Ikuti prosedur penurunan versi manual di bawah. Prosedur ini tidak didukung dan berisiko menyebabkan kehilangan data tanpa cadangan yang telah diverifikasi.

Sejak 2026.7.2, openclaw update menolak menginstal rilis yang tidak dapat membuka basis data Anda saat ini, sehingga pemutakhir tidak akan menempatkan Anda dalam situasi ini. Menginstal versi lama secara manual melalui npm melewati pengaman tersebut; basis data tetap menolak biner lama, tetapi hanya setelah biner tersebut diinstal.

Gateway menolak dimulai karena galat versi skema yang lebih baru

Build OpenClaw yang lebih baru menulis basis data Anda, dan build yang sedang berjalan lebih lama. Galat dan log awal Gateway menyebutkan build pemilik basis data (app_version). Instal versi tersebut atau yang lebih baru, atau gunakan salah satu opsi di atas. Jangan mengedit basis data untuk membungkam galat tersebut.

Basis data dikarantina setelah verifikasi integritas gagal

Pemverifikasi latar belakang membuktikan bahwa berkas tersebut rusak, dan setiap pembukaan kini langsung gagal alih-alih memindai ulang. Pulihkan basis data dari cadangan atau perbaiki, lalu jalankan openclaw doctor --fix untuk menghapus catatan karantina. Doctor melaporkan galat eksplisit jika catatan karantina itu sendiri tidak dapat dihapus; jalankan ulang hingga Doctor melaporkan kondisi bersih.

Penurunan versi tidak didukung

Penurunan versi skema manual ditujukan bagi agen dan operator yang menerima risikonya. Buat dan verifikasi cadangan sebelum mengedit basis data apa pun. Hentikan Gateway dan setiap proses yang dapat membuka basis data.

Prosedur umumnya adalah:

1. Baca skema dan migrasi rilis target.
2. Dalam satu transaksi, hapus setiap tabel, indeks, pemicu, dan kolom yang diperkenalkan setelah versi target.
3. Tetapkan PRAGMA user_version dan schema_meta.schema_version ke versi target.
4. Jalankan verifikasi basis data lengkap dari rilis target sebelum memulai Gateway.

Contoh: skema agen 11 ke 9

Skema 10 menambahkan proyeksi transkrip aktif. Skema 11 menambahkan sewa, pengiriman tahan lama, status alamat percakapan, dan hasil heartbeat. Koordinasi QMD menggunakan baris dalam state_leases; tidak ada tabel QMD terpisah yang perlu dipertahankan.

Jalankan SQL yang setara terhadap setiap basis data per agen yang terpengaruh setelah memeriksa skema persis yang menulisnya:

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;

Tindakan ini membuang status versi 10-11, termasuk operasi pengiriman yang sedang berlangsung, sewa, hasil heartbeat, dan proyeksi transkrip aktif turunan. Jika penurunan versi gagal, pulihkan dari cadangan yang telah diverifikasi.