डेटाबेस स्कीमा

OpenClaw नियंत्रण-प्लेन की स्थिति को एक वैश्विक SQLite डेटाबेस में और एजेंट डेटा को प्रत्येक एजेंट के लिए एक SQLite डेटाबेस में संग्रहीत करता है। डेटाबेस खुलने पर स्कीमा माइग्रेशन आगे की ओर चलते हैं। OpenClaw के पुराने बिल्ड नए स्कीमा द्वारा लिखे गए डेटाबेस को अस्वीकार कर देते हैं।

डेटाबेस विन्यास

दायरा	डिफ़ॉल्ट पथ	सामग्री
वैश्विक नियंत्रण प्लेन	`~/.openclaw/state/openclaw.sqlite`	साझा कॉन्फ़िगरेशन स्थिति, रजिस्ट्रियाँ, अनुमोदन, Plugin स्थिति और साझा रनटाइम स्थिति
प्रति-एजेंट डेटा प्लेन	`~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite`	सत्र, ट्रांसक्रिप्ट, मेमोरी इंडेक्स, प्रमाणीकरण स्थिति, वार्तालाप स्थिति और एजेंट-दायरे की रनटाइम स्थिति

कुछ अधिक-वॉल्यूम या जीवनचक्र-विशिष्ट सुविधाएँ समर्पित SQLite स्टोर का उपयोग करती हैं, जिनमें कार्य रजिस्ट्री और ट्रैजेक्टरी डेटा शामिल हैं।

संस्करण अनुबंध

प्रत्येक डेटाबेस अपना स्कीमा दो स्थानों पर दर्ज करता है:

PRAGMA user_version SQLite स्कीमा संस्करण है।
प्राथमिक schema_meta पंक्ति role, agent_id, schema_version, और app_version दर्ज करती है। app_version वह OpenClaw बिल्ड है जिसने अंतिम बार स्कीमा मेटाडेटा लिखा था।

OpenClaw किसी पुराने समर्थित डेटाबेस को खोलते समय केवल आगे की ओर माइग्रेशन लागू करता है। यह ऐसे डेटाबेस को अस्वीकार कर देता है जिसका user_version चल रहे बिल्ड से नया हो और newer schema version त्रुटि रिपोर्ट करता है। Gateway स्टार्टअप से पहले सभी पंजीकृत डेटाबेस की जाँच करता है। openclaw update ऐसे पैकेज या स्रोत लक्ष्य को भी अस्वीकार करता है जिसका घोषित स्कीमा समर्थन डिस्क पर मौजूद डेटाबेस से पुराना हो। स्कीमा मेटाडेटा जोड़े जाने से पहले प्रकाशित लक्ष्य पैकेजों की पूर्व-जाँच नहीं की जा सकती। npm के माध्यम से OpenClaw को मैन्युअल रूप से इंस्टॉल करने पर अपडेटर सुरक्षा-जाँच बायपास हो जाती है। डेटाबेस खोलने की जाँच फिर भी असंगत बिल्ड को अस्वीकार करती है।

एजेंट स्कीमा इतिहास

संस्करण	परिवर्तन	पहला रिलीज़
1	आरंभिक प्रति-एजेंट स्टोर (#88349)	`v2026.5.30-beta.1`, `v2026.7.1` तक स्थिर
2	मेमोरी इंडेक्स पहचान (#104449)	`v2026.7.2-beta.1`
4	सत्र और ट्रांसक्रिप्ट SQLite में स्थानांतरित किए गए (#98236)	`v2026.7.2-beta.1`
5-6	टर्मिनल नवीनता और स्थिति जीवनचक्र (#104859)	`v2026.7.2-beta.1`
7	प्रति-प्रविष्टि जीवनचक्र स्थिति प्रक्षेपण (#106151)	`v2026.7.2-beta.1`
8	प्रति-ट्रांसक्रिप्ट सत्र उद्गम (#106766)	`v2026.7.2-beta.2`
9	`STRICT` तालिकाएँ (#108663)	`v2026.7.2-beta.2`
10	मूर्त रूप दिए गए सक्रिय ट्रांसक्रिप्ट पथ (#108851)	अप्रकाशित
11	लीज़, टिकाऊ डिलीवरी, वार्तालाप पते और Heartbeat परिणाम (#109636, #95838, #109999)	अप्रकाशित

संस्करण 3 एक अप्रकाशित विकास चरण था जिसे संस्करण 4 में समाहित कर दिया गया।

स्थिति स्कीमा इतिहास

संस्करण	परिवर्तन	पहला रिलीज़
1	आरंभिक साझा स्थिति डेटाबेस	`v2026.5.30-beta.1`
2	केवल-मेटाडेटा संदेश ऑडिट इवेंट (#103903)	`v2026.7.2-beta.1`
3	`STRICT` तालिकाएँ और स्कीमा-विचलन सुदृढ़ीकरण (#108663)	`v2026.7.2-beta.2`
4	सत्र निगरानी उद्गम ने एन्कोडेड सेंटिनल पंक्तियों का स्थान लिया	अप्रकाशित

अखंडता जाँच

कब	जाँच
प्रत्येक बार खोलने पर	`schema_meta` तालिका और प्राथमिक मेटाडेटा पंक्ति सत्यापित करें
लंबित माइग्रेशन से पहले	पूर्ण अखंडता, फ़ॉरेन-की, भूमिका, स्कीमा और इंडेक्स स्कैन चलाएँ
Gateway पृष्ठभूमि सत्यापनकर्ता	लगभग प्रतिदिन एक बार पूर्ण स्कैन चलाएँ और परिणाम लॉग करें
Doctor, बैकअप सत्यापन और Compaction	डेटाबेस स्वीकार करने या दोबारा लिखने से पहले पूर्ण स्कैन चलाएँ

Gateway की पूर्व-जाँच केवल स्कीमा हेडर पढ़ती है। जिन डेटाबेस को माइग्रेशन की आवश्यकता नहीं है, उनके लिए धीमे पूर्ण स्कैन का स्वामित्व पृष्ठभूमि सत्यापनकर्ता के पास है। क्वारंटीन निर्णय केवल एक समर्पित openclaw-quarantine.sqlite स्टोर में रहते हैं, इसलिए वे क्वारंटीन किए जा रहे डेटाबेस को हुई क्षति के बाद भी बने रहते हैं। सत्यापन परिणाम लॉग किए जाते हैं।

समस्या निवारण

2026.7.2 में अपडेट करने के बाद वापस क्यों नहीं जा सकते

v2026.7.1 तक प्रत्येक रिलीज़ में एजेंट स्कीमा 1 और स्थिति स्कीमा 1 का उपयोग हुआ। 2026.7.2 रिलीज़ शृंखला (v2026.7.2-beta.1 से शुरू) पहले स्टार्ट पर आपके डेटाबेस को आगे माइग्रेट करती है। यह माइग्रेशन एकतरफ़ा है: डेटा को नए स्कीमा में दोबारा लिखा जाता है और उसके बाद पुराने OpenClaw को इंस्टॉल करने से यह पूर्ववत नहीं होता। पुराना बिल्ड newer schema version त्रुटि के साथ स्टार्ट होने से इनकार करता है, जिसमें डेटाबेस के स्वामी बिल्ड का नाम दिया जाता है। बाइनरी को डाउनग्रेड करने से डेटा कभी डाउनग्रेड नहीं होता। यदि अपडेट करने के बाद 2026.7.2 से पुरानी रिलीज़ चलाना आवश्यक हो, तो आपके पास तीन विकल्प हैं:

अपडेट से पहले लिया गया बैकअप पुनर्स्थापित करें। बड़े अपडेट से पहले बैकअप बनाएँ और सत्यापित करें।
पुराने बिल्ड को एक अलग स्थिति डायरेक्टरी (OPENCLAW_STATE_DIR) के साथ चलाएँ। यह नए सिरे से शुरू होता है; जब आप नए बिल्ड पर वापस आते हैं, तब तक आपका माइग्रेट किया गया डेटा अछूता रहता है।
नीचे दी गई मैन्युअल डाउनग्रेड प्रक्रिया का पालन करें। यह असमर्थित है और सत्यापित बैकअप के बिना डेटा हानि का जोखिम पैदा करती है।

2026.7.2 से, openclaw update ऐसी रिलीज़ इंस्टॉल करने से इनकार करता है जो आपके वर्तमान डेटाबेस नहीं खोल सकती, इसलिए अपडेटर आपको इस स्थिति में नहीं डालेगा। npm के माध्यम से पुराना संस्करण मैन्युअल रूप से इंस्टॉल करने पर यह सुरक्षा-जाँच बायपास हो जाती है; डेटाबेस फिर भी पुरानी बाइनरी को अस्वीकार करते हैं, लेकिन उसके इंस्टॉल हो जाने के बाद।

Gateway नए स्कीमा संस्करण की त्रुटि के साथ स्टार्ट होने से इनकार करता है

किसी नए OpenClaw बिल्ड ने आपके डेटाबेस लिखे थे और चल रहा बिल्ड पुराना है। त्रुटि और Gateway स्टार्टअप लॉग डेटाबेस के स्वामी बिल्ड (app_version) का नाम देते हैं। वह संस्करण या उससे नया संस्करण इंस्टॉल करें, या ऊपर दिए गए विकल्पों में से किसी एक का उपयोग करें। त्रुटि दबाने के लिए डेटाबेस संपादित न करें।

अखंडता सत्यापन विफल होने के बाद डेटाबेस क्वारंटीन किया गया है

पृष्ठभूमि सत्यापनकर्ता ने सिद्ध किया कि फ़ाइल दूषित है और अब हर बार खोलना दोबारा स्कैन करने के बजाय तुरंत विफल होता है। डेटाबेस को बैकअप से पुनर्स्थापित करें या उसकी मरम्मत करें, फिर क्वारंटीन रिकॉर्ड साफ़ करने के लिए openclaw doctor --fix चलाएँ। यदि क्वारंटीन रिकॉर्ड स्वयं साफ़ नहीं किया जा सकता, तो Doctor एक स्पष्ट त्रुटि रिपोर्ट करता है; इसे तब तक दोबारा चलाएँ जब तक यह सब ठीक होने की रिपोर्ट न करे।

डाउनग्रेड असमर्थित हैं

मैन्युअल स्कीमा डाउनग्रेड उन एजेंटों और ऑपरेटरों के लिए हैं जो जोखिम स्वीकार करते हैं। किसी डेटाबेस को संपादित करने से पहले बैकअप बनाएँ और सत्यापित करें। Gateway और डेटाबेस खोल सकने वाली प्रत्येक प्रक्रिया को रोकें। सामान्य प्रक्रिया यह है:

लक्ष्य रिलीज़ के स्कीमा और माइग्रेशन पढ़ें।
एक ट्रांज़ैक्शन में, लक्ष्य संस्करण के बाद प्रस्तुत की गई प्रत्येक तालिका, इंडेक्स, ट्रिगर और कॉलम हटाएँ।
PRAGMA user_version और schema_meta.schema_version को लक्ष्य संस्करण पर सेट करें।
Gateway स्टार्ट करने से पहले लक्ष्य रिलीज़ का पूर्ण डेटाबेस सत्यापन चलाएँ।

उदाहरण: एजेंट स्कीमा 11 से 9

स्कीमा 10 ने सक्रिय ट्रांसक्रिप्ट प्रक्षेपण जोड़ा। स्कीमा 11 ने लीज़, टिकाऊ डिलीवरी, वार्तालाप-पता स्थिति और Heartbeat परिणाम जोड़े। QMD समन्वय state_leases की पंक्तियों का उपयोग करता है; संरक्षित करने के लिए कोई अलग QMD तालिका नहीं है। प्रत्येक प्रभावित प्रति-एजेंट डेटाबेस को लिखने वाले सटीक स्कीमा का निरीक्षण करने के बाद उसके विरुद्ध समकक्ष SQL चलाएँ:

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;

यह संस्करण 10-11 की स्थिति को त्याग देता है, जिसमें जारी डिलीवरी संचालन, लीज़, Heartbeat परिणाम और व्युत्पन्न सक्रिय ट्रांसक्रिप्ट प्रक्षेपण शामिल हैं। विफल डाउनग्रेड होने पर सत्यापित बैकअप से पुनर्स्थापित करें।

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

डेटाबेस स्कीमा

डेटाबेस विन्यास

संस्करण अनुबंध

एजेंट स्कीमा इतिहास

स्थिति स्कीमा इतिहास

अखंडता जाँच

समस्या निवारण

2026.7.2 में अपडेट करने के बाद वापस क्यों नहीं जा सकते

Gateway नए स्कीमा संस्करण की त्रुटि के साथ स्टार्ट होने से इनकार करता है

अखंडता सत्यापन विफल होने के बाद डेटाबेस क्वारंटीन किया गया है

डाउनग्रेड असमर्थित हैं

उदाहरण: एजेंट स्कीमा 11 से 9

​डेटाबेस विन्यास

​संस्करण अनुबंध

​एजेंट स्कीमा इतिहास

​स्थिति स्कीमा इतिहास

​अखंडता जाँच

​समस्या निवारण

​2026.7.2 में अपडेट करने के बाद वापस क्यों नहीं जा सकते

​Gateway नए स्कीमा संस्करण की त्रुटि के साथ स्टार्ट होने से इनकार करता है

​अखंडता सत्यापन विफल होने के बाद डेटाबेस क्वारंटीन किया गया है

​डाउनग्रेड असमर्थित हैं

​उदाहरण: एजेंट स्कीमा 11 से 9

डेटाबेस विन्यास

संस्करण अनुबंध

एजेंट स्कीमा इतिहास

स्थिति स्कीमा इतिहास

अखंडता जाँच

समस्या निवारण

2026.7.2 में अपडेट करने के बाद वापस क्यों नहीं जा सकते

Gateway नए स्कीमा संस्करण की त्रुटि के साथ स्टार्ट होने से इनकार करता है

अखंडता सत्यापन विफल होने के बाद डेटाबेस क्वारंटीन किया गया है

डाउनग्रेड असमर्थित हैं

उदाहरण: एजेंट स्कीमा 11 से 9