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

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

डेटाबेस संरचना

अधिक मात्रा वाले या जीवनचक्र-विशिष्ट कुछ फ़ीचर समर्पित 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 को मैन्युअल रूप से इंस्टॉल करने पर अपडेटर सुरक्षा-जाँच बायपास हो जाती है। डेटाबेस खोलने की जाँचें फिर भी असंगत बिल्ड को अस्वीकार करती हैं।

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

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

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

अखंडता जाँचें

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 से पुराना रिलीज़ चलाना आवश्यक है, तो आपके पास तीन विकल्प हैं:

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

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

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

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

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

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

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

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

सामान्य प्रक्रिया यह है:

1. लक्ष्य रिलीज़ का स्कीमा और माइग्रेशन पढ़ें।
2. एक ट्रांज़ैक्शन में, लक्ष्य संस्करण के बाद प्रस्तुत की गई प्रत्येक तालिका, इंडेक्स, ट्रिगर और कॉलम हटाएँ।
3. PRAGMA user_version और schema_meta.schema_version को लक्ष्य संस्करण पर सेट करें।
4. 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_metaSET schema_version = 9,    updated_at = unixepoch('now') * 1000WHERE meta_key = 'primary'; COMMIT;

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