सत्र प्रबंधन का गहन विश्लेषण

एकल Gateway प्रक्रिया सत्र की स्थिति का शुरू से अंत तक स्वामित्व रखती है। UI (macOS ऐप, वेब Control UI, TUI) सत्र सूचियों और टोकन गणनाओं के लिए Gateway से क्वेरी करते हैं। रिमोट मोड में, सत्र फ़ाइलें रिमोट होस्ट पर रहती हैं, इसलिए आपके स्थानीय Mac की फ़ाइलों की जाँच से यह पता नहीं चलेगा कि Gateway क्या उपयोग कर रहा है।

पहले अवलोकन दस्तावेज़ देखें: सत्र प्रबंधन, Compaction, मेमोरी अवलोकन, मेमोरी खोज, सत्र छँटाई, ट्रांसक्रिप्ट स्वच्छता, पूर्ण कॉन्फ़िगरेशन संदर्भ एजेंट कॉन्फ़िगरेशन पर उपलब्ध है।

दो स्थायित्व परतें

1. सत्र पंक्तियाँ (प्रति-एजेंट SQLite) - कुंजी/मान मैप sessionKey -> SessionEntry। Gateway के स्वामित्व वाली परिवर्तनशील रनटाइम स्थिति। मेटाडेटा ट्रैक करती है: वर्तमान सत्र आईडी, अंतिम गतिविधि, टॉगल, टोकन काउंटर।
2. ट्रांसक्रिप्ट इवेंट (प्रति-एजेंट SQLite) - केवल-संयोजन, वृक्ष-संरचित (प्रविष्टियों में id + parentId होते हैं)। वार्तालाप, टूल कॉल और Compaction सारांश संग्रहीत करता है; भविष्य के टर्न के लिए मॉडल संदर्भ फिर से बनाता है। Compaction चेकपॉइंट संकुचित उत्तरवर्ती ट्रांसक्रिप्ट के ऊपर मेटाडेटा होते हैं - नया Compaction दूसरी .checkpoint.*.jsonl प्रति नहीं लिखता।

पुराने इंस्टॉलेशन में अभी भी एजेंट की sessions/ डायरेक्टरी के अंतर्गत sessions.json फ़ाइलें हो सकती हैं। उन फ़ाइलों को लीगेसी सत्र-पंक्ति माइग्रेशन इनपुट या स्पष्ट ऑफ़लाइन-रखरखाव लक्ष्य मानें। Gateway स्टार्टअप और openclaw doctor --fix, सक्रिय लीगेसी पंक्तियों और ट्रांसक्रिप्ट इतिहास को स्वचालित रूप से प्रति-एजेंट SQLite स्टोर में आयात करते हैं। जब स्पष्ट निरीक्षण या सत्यापन प्रमाण की आवश्यकता हो, तो openclaw doctor --session-sqlite inspect --session-sqlite-all-agents चलाएँ, फिर Doctor माइग्रेशन क्रम का पालन करें। यदि लीगेसी ट्रांसक्रिप्ट आर्टिफ़ैक्ट संग्रहित किए जाने के बाद माइग्रेशन विफल हो जाए, तो उस क्रम से Doctor पुनर्प्राप्ति मोड का उपयोग करें। पुनर्प्राप्ति माइग्रेशन मैनिफ़ेस्ट का उपयोग करती है, केवल प्रभावित संग्रहित सहायक आर्टिफ़ैक्ट पुनर्स्थापित करती है, अनुरोध किए जाने पर स्वच्छीकृत GitHub इश्यू रिपोर्ट तैयार करती है, और सक्रिय रनटाइम को JSONL फ़ाइलें फिर से पढ़ने नहीं देती।

Gateway इतिहास रीडर पूरे ट्रांसक्रिप्ट को मेमोरी में लाने से बचते हैं, जब तक सतह को मनचाही ऐतिहासिक पहुँच की आवश्यकता न हो। प्रथम-पृष्ठ इतिहास, एम्बेडेड चैट इतिहास, पुनरारंभ पुनर्प्राप्ति और टोकन/उपयोग जाँच SQLite से सीमित टेल रीड का उपयोग करते हैं। पूर्ण ट्रांसक्रिप्ट स्कैन एसिंक ट्रांसक्रिप्ट इंडेक्स से गुजरते हैं और समवर्ती रीडर के बीच साझा किए जाते हैं।

डिस्क पर स्थान

प्रति एजेंट, Gateway होस्ट पर (src/config/sessions.ts के माध्यम से निर्धारित):

• रनटाइम सत्र पंक्ति स्टोर: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• रनटाइम ट्रांसक्रिप्ट पंक्तियाँ: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite
• लीगेसी/संग्रह ट्रांसक्रिप्ट आर्टिफ़ैक्ट: ~/.openclaw/agents/<agentId>/sessions/
• लीगेसी पंक्ति माइग्रेशन इनपुट: ~/.openclaw/agents/<agentId>/sessions/sessions.json

स्टोर रखरखाव और डिस्क नियंत्रण

session.maintenance, SQLite सत्र पंक्तियों, SQLite ट्रांसक्रिप्ट पंक्तियों, संग्रह आर्टिफ़ैक्ट और ट्रैजेक्टरी साइडकार के स्वचालित रखरखाव को नियंत्रित करता है:

रीसेट सक्रिय sessionKey -> sessionId मैपिंग को आगे बढ़ाता है, लेकिन पिछली SQLite सत्र, ट्रांसक्रिप्ट, ट्रैजेक्टरी और खोज पंक्तियाँ बनाए रखता है। वह इतिहास उसी सत्र कुंजी के अंतर्गत खोज योग्य रहता है; सामान्य प्रविष्टि और सत्र सूचियाँ केवल नई सक्रिय मैपिंग दिखाती हैं। बनाए रखा गया रीसेट इतिहास डिस्क बजट द्वारा सीमित होता है, resetArchiveRetention द्वारा नहीं, जो केवल संग्रह आर्टिफ़ैक्ट की आयु निर्धारित करता है। स्पष्ट विलोपन अलग है: हटाए गए सत्र की पंक्तियाँ निकालने से पहले यह संपीड़ित ट्रांसक्रिप्ट संग्रह लिखता और सत्यापित करता है (zstd उपलब्ध होने पर *.jsonl.deleted.<timestamp>.zst)।

maxDiskBytes प्रवर्तन भौतिक बाइट का उपयोग करता है: प्रति-एजेंट SQLite मुख्य फ़ाइल, उसकी -wal फ़ाइल, और एजेंट सत्र डायरेक्टरी में गिनी गई फ़ाइलें। यह कभी पंक्ति JSON आकार का अनुमान नहीं लगाता या उस कुल से तार्किक पंक्ति आकार नहीं घटाता।

Gateway मॉडल-रन प्रोब सत्रों (जिनकी कुंजियाँ agent:*:explicit:model-run-<uuid> से मेल खाती हैं) के लिए अलग, निश्चित 24h अवधारण होती है। यह छँटाई दबाव-आधारित है: यह केवल तभी चलती है जब सत्र-प्रविष्टि रखरखाव/सीमा का दबाव पहुँच जाता है, और वैश्विक बासी-प्रविष्टि सफ़ाई/सीमा चरण से केवल पहले चलती है। अन्य स्पष्ट सत्र इस अवधारण का उपयोग नहीं करते।

जब संयुक्त भौतिक उपयोग maxDiskBytes से अधिक हो जाता है, तो mode: "enforce" पहले चेकपॉइंट किए जा सकने वाले डेटाबेस स्थान को पुनः प्राप्त करता है, फिर बनाए रखे गए सबसे पुराने रीसेट/विलोपन संग्रह हटाता है। यदि उपयोग अभी भी highWaterBytes से अधिक है, तो यह sessions.updated_at के अनुसार ऐतिहासिक SQLite सत्रों को सबसे पुराने से शुरू करके देखता है। ऐतिहासिक का अर्थ है कि सत्र आईडी किसी सक्रिय सत्र प्रविष्टि, रूट लक्ष्य या स्वीकृत/प्रगतिशील रन द्वारा संदर्भित नहीं है। प्रत्येक चयनित सत्र के लिए, सफ़ाई संपीड़ित संग्रह को लिखती, fsync करती और वापस पढ़ती है, जिसके बाद एक राइट ट्रांज़ैक्शन सत्र पंक्ति और उसके ट्रांसक्रिप्ट, ट्रैजेक्टरी, सक्रिय, इंडेक्स तथा FTS प्रोजेक्शन हटाता है। इसमें वे सत्र भी शामिल हैं जिनमें ट्रैजेक्टरी इवेंट हैं लेकिन ट्रांसक्रिप्ट इवेंट नहीं हैं। सफ़ाई विलोपन के समय रूट, प्रविष्टि और स्वीकृति संदर्भों को फिर से जाँचती है, प्रत्येक संग्रह या चयनित सत्र के बाद भौतिक उपयोग को फिर से मापती है और highWaterBytes पर रुकती है।

कमिट किए गए लेखन और विलोपन पहले WAL में पहुँचते हैं। सफ़ाई इसका चेकपॉइंट बनाती है ताकि WAL तुरंत छोटा हो सके, फिर मुख्य फ़ाइल से योग्य मुक्त अंतिम पृष्ठ लौटाने के लिए इंक्रीमेंटल वैक्यूम का उपयोग करती है; जो पृष्ठ अभी पुनः प्राप्त करने योग्य नहीं हैं वे मुख्य फ़ाइल में रहते हैं और इसलिए अगले भौतिक मापन में गिने जाते हैं। mode: "warn" बिना चेकपॉइंट बनाए, संग्रह लिखे या पंक्तियाँ हटाए वर्तमान भौतिक अधिकता की रिपोर्ट करता है।

माँग पर रखरखाव चलाएँ:

openclaw sessions cleanup --dry-runopenclaw sessions cleanup --enforce

रखरखाव समूह सत्र और थ्रेड-स्कोप्ड चैट सत्र जैसे स्थायी बाहरी वार्तालाप पॉइंटर बनाए रखता है, लेकिन सिंथेटिक रनटाइम प्रविष्टियाँ (Cron, हुक, Heartbeat, ACP, उप-एजेंट) कॉन्फ़िगर की गई आयु, संख्या या डिस्क बजट पार करने के बाद भी हटाई जा सकती हैं। पृथक Cron रन, मॉडल-रन प्रोब अवधारण से स्वतंत्र एक अलग cron.sessionRetention नियंत्रण का उपयोग करते हैं।

सामान्य Gateway लेखन सत्र एक्सेसर से गुजरते हैं, जो रनटाइम राइटर पथ के माध्यम से प्रति-एजेंट SQLite परिवर्तनों को क्रमबद्ध करता है। रनटाइम कोड को src/config/sessions/session-accessor.ts में एक्सेसर हेल्पर को प्राथमिकता देनी चाहिए; लीगेसी sessions.json हेल्पर माइग्रेशन और ऑफ़लाइन-रखरखाव टूल हैं। जब Gateway उपलब्ध हो, तो गैर-ड्राई-रन openclaw sessions cleanup और openclaw agents delete स्टोर परिवर्तनों को Gateway को सौंपते हैं ताकि सफ़ाई उसी राइटर कतार में शामिल हो; --store <path> चयनित लीगेसी स्टोर का स्पष्ट ऑफ़लाइन मरम्मत पथ है और हमेशा स्थानीय रहता है (जैसे --dry-run)। maxEntries सफ़ाई उत्पादन-आकार के स्टोरों के लिए बैच में होती है, इसलिए अगली हाई-वॉटर सफ़ाई द्वारा स्टोर को कॉन्फ़िगर की गई सीमा तक फिर से घटाने से पहले वह कुछ समय के लिए सीमा पार कर सकता है। रीड कभी भी Gateway स्टार्टअप के दौरान प्रविष्टियों की छँटाई या सीमा लागू नहीं करते - केवल राइट या openclaw sessions cleanup --enforce ऐसा करते हैं, और बाद वाला सीमा को तुरंत लागू भी करता है तथा बिना किसी डिस्क बजट के कॉन्फ़िगर होने पर भी पुरानी असंदर्भित लीगेसी ट्रांसक्रिप्ट, चेकपॉइंट और ट्रैजेक्टरी आर्टिफ़ैक्ट की छँटाई करता है।

OpenClaw अब Gateway लेखन के दौरान स्वचालित sessions.json.bak.* रोटेशन बैकअप नहीं बनाता। वर्तमान स्कीमा लीगेसी session.maintenance.rotateBytes कुंजी को अस्वीकार करता है, और openclaw doctor --fix इसे पुराने कॉन्फ़िगरेशन से हटा देता है।

ट्रांसक्रिप्ट परिवर्तन SQLite ट्रांसक्रिप्ट लक्ष्य के लिए सत्र लेखन कतार का उपयोग करते हैं:

सत्र लेखन लॉक निश्चित उत्पादन डिफ़ॉल्ट का उपयोग करते हैं। संबंधित OPENCLAW_SESSION_WRITE_LOCK_* पर्यावरण चर प्रक्रिया-स्तरीय निदान और आपातकालीन ओवरराइड के लिए उपलब्ध रहते हैं।

SQLite परिवर्तन के बाद डाउनग्रेड करना

पुराना फ़ाइल-समर्थित OpenClaw संस्करण चलाने से पहले संग्रहित लीगेसी ट्रांसक्रिप्ट आर्टिफ़ैक्ट पुनर्स्थापित करें:

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

माइग्रेशन सहायता और रोलबैक के लिए लीगेसी sessions.json फ़ाइलों को यथास्थान छोड़ता है, लेकिन SQLite में आयात की गई सक्रिय ट्रांसक्रिप्ट JSONL फ़ाइलों का नाम बदलकर session-sqlite-import-archive/ कर दिया जाता है। पुराने फ़ाइल-समर्थित रनटाइम sessions.json में sessionFile पथों का अनुसरण करते हैं, इसलिए स्टार्टअप से पहले उन्हें वे आर्टिफ़ैक्ट पुनर्स्थापित करने होते हैं। पुनर्स्थापन माइग्रेशन मैनिफ़ेस्ट का उपयोग करता है, केवल दर्ज किए गए उन संग्रहित आर्टिफ़ैक्ट को स्थानांतरित करता है जिनके मूल पथ अनुपस्थित हैं, और आगे की पुनर्प्राप्ति के लिए SQLite डेटाबेस को यथास्थान छोड़ देता है।

SQLite परिवर्तन के बाद बनाए गए सत्र केवल SQLite में होते हैं और पुराने फ़ाइल-समर्थित रनटाइम को दिखाई नहीं देंगे। यदि डाउनग्रेड के बाद फिर से अपग्रेड करें, तो Doctor निरीक्षण और सत्यापन क्रम फिर चलाएँ ताकि OpenClaw आयात से पहले पुनर्स्थापित लीगेसी आर्टिफ़ैक्ट सत्यापित कर सके।

Cron सत्र और रन लॉग

पृथक Cron रन समर्पित अवधारण के साथ अपनी स्वयं की सत्र प्रविष्टियाँ/ट्रांसक्रिप्ट बनाते हैं:

• cron.sessionRetention (डिफ़ॉल्ट "24h") स्टोर से पुराने पृथक Cron रन सत्रों की छँटाई करता है; false इसे अक्षम करता है।
• रन इतिहास प्रत्येक Cron जॉब के लिए नवीनतम 2000 अंतिम पंक्तियाँ बनाए रखता है। खोई हुई पंक्तियाँ अपनी 24-घंटे की सफ़ाई अवधि बनाए रखती हैं।

जब Cron बलपूर्वक नया पृथक रन सत्र बनाता है, तो नई पंक्ति लिखने से पहले पिछली cron:<jobId> सत्र प्रविष्टि को स्वच्छ करता है: यह सुरक्षित प्राथमिकताएँ (सोच/तेज़/वर्बोज़/रीज़निंग सेटिंग, लेबल, प्रदर्शन नाम) और स्पष्ट उपयोगकर्ता-चयनित मॉडल/प्रमाणीकरण ओवरराइड आगे ले जाता है, लेकिन परिवेशी वार्तालाप संदर्भ (चैनल/समूह रूटिंग, प्रेषण/कतार नीति, उन्नयन, मूल, ACP रनटाइम बाइंडिंग) हटा देता है, ताकि नया पृथक रन किसी पुराने रन से बासी डिलीवरी या रनटाइम प्राधिकार विरासत में न ले सके।

सत्र कुंजियाँ (sessionKey)

एक sessionKey यह पहचानता है कि आप किस वार्तालाप बकेट में हैं (रूटिंग + पृथक्करण)। कैनोनिकल नियम: /concepts/session।

सत्र आईडी (sessionId)

प्रत्येक sessionKey वर्तमान sessionId (वह SQLite ट्रांसक्रिप्ट पहचान जो वार्तालाप जारी रखती है) की ओर इंगित करता है। निर्णय तर्क src/auto-reply/reply/session.ts के initSessionState() में रहता है।

• रीसेट (/new, /reset) उस sessionKey के लिए एक नया sessionId बनाता है।
• कोई स्वचालित रीसेट नहीं डिफ़ॉल्ट है। वर्तमान sessionId जारी रहता है, जबकि Compaction सक्रिय मॉडल संदर्भ को सीमित रखता है।
• दैनिक रीसेट (session.reset.mode: "daily") कॉन्फ़िगर की गई स्थानीय-घंटे की सीमा (session.reset.atHour, डिफ़ॉल्ट 4) के बाद अगले संदेश पर एक नया sessionId बनाता है।
• निष्क्रियता समाप्ति (session.reset.mode: "idle" के साथ session.reset.idleMinutes, या पुराना session.idleMinutes) निष्क्रियता अवधि के बाद कोई संदेश आने पर एक नया sessionId बनाती है। यदि दैनिक और निष्क्रियता, दोनों कॉन्फ़िगर हैं, तो जो पहले समाप्त होता है वही प्रभावी होता है।
• Control UI के पुनः कनेक्ट होने पर पुनरारंभ वर्तमान में दिखाई देने वाले सत्र को पुनः कनेक्ट होने के बाद भेजे जाने वाले एक संदेश के लिए सुरक्षित रखता है, जब Gateway को किसी ऑपरेटर UI क्लाइंट से मेल खाने वाला sessionId प्राप्त होता है। यह एक बार उपयोग होने वाला संकेत है; सामान्य पुराने प्रेषण अब भी एक नया sessionId बनाते हैं।
• सिस्टम इवेंट (Heartbeat, Cron वेकअप, exec सूचनाएँ, Gateway बहीखाता) सत्र पंक्ति को बदल सकते हैं, लेकिन दैनिक/निष्क्रियता रीसेट की नवीनता को कभी नहीं बढ़ाते। रीसेट रोलओवर नया प्रॉम्प्ट बनने से पहले पिछले सत्र के लिए कतारबद्ध सिस्टम-इवेंट सूचनाएँ हटा देता है।
• पैरेंट फ़ोर्क नीति थ्रेड या सबएजेंट फ़ोर्क बनाते समय OpenClaw की सक्रिय शाखा का उपयोग करती है। यदि वह शाखा बहुत बड़ी है (एक निश्चित आंतरिक सीमा से अधिक, वर्तमान में 100K टोकन), तो OpenClaw विफल होने या अनुपयोगी इतिहास इनहेरिट करने के बजाय चाइल्ड को पृथक संदर्भ के साथ शुरू करता है। आकार निर्धारण स्वचालित है और कॉन्फ़िगर करने योग्य नहीं है; पुराने session.parentForkMaxTokens कॉन्फ़िग को openclaw doctor --fix द्वारा हटा दिया जाता है।
• ऑपरेटर फ़ोर्क: sessions.create { parentSessionKey, fork: true } एक नया सत्र बनाता है, जिसका ट्रांसक्रिप्ट पैरेंट की वर्तमान स्थिति से शाखित होता है (सबएजेंट स्पॉन के समान फ़ोर्क तंत्र, जिसमें ऊपर दी गई आकार सीमा भी शामिल है)। पैरेंट का कोई सक्रिय रन होने पर फ़ोर्क अस्वीकार कर दिया जाता है, स्पष्ट रूप से कोई चयन न दिए जाने तक यह पैरेंट का मॉडल चयन इनहेरिट करता है, और चाइल्ड forkedFromParent को नए टोकन काउंटर के साथ चिह्नित करता है।

सत्र स्टोर स्कीमा

रनटाइम स्टोर प्रति-एजेंट SQLite में SessionEntry मान रखता है। मान का प्रकार src/config/sessions.ts में SessionEntry है। मुख्य फ़ील्ड (संपूर्ण सूची नहीं):

• sessionId: SQLite ट्रांसक्रिप्ट पंक्तियों को संबोधित करने के लिए प्रयुक्त वर्तमान ट्रांसक्रिप्ट आईडी
• sessionStartedAt: वर्तमान sessionId का आरंभ टाइमस्टैम्प; दैनिक रीसेट की नवीनता इसका उपयोग करती है। पुरानी पंक्तियाँ इसे JSONL सत्र हेडर से प्राप्त कर सकती हैं।
• lastInteractionAt: अंतिम वास्तविक उपयोगकर्ता/चैनल इंटरैक्शन का टाइमस्टैम्प; निष्क्रियता रीसेट की नवीनता इसका उपयोग करती है, ताकि Heartbeat, Cron और exec इवेंट सत्रों को सक्रिय न रखें। इस फ़ील्ड के बिना पुरानी पंक्तियाँ पुनर्प्राप्त सत्र आरंभ समय का उपयोग करती हैं।
• updatedAt: अंतिम स्टोर-पंक्ति परिवर्तन का टाइमस्टैम्प, जिसका उपयोग सूचीकरण/छँटाई/बहीखाते के लिए किया जाता है—यह दैनिक/निष्क्रियता नवीनता का प्राधिकार नहीं है।
• archivedAt: वैकल्पिक संग्रह टाइमस्टैम्प। संग्रहित सत्र अपने अक्षुण्ण ट्रांसक्रिप्ट के साथ स्टोर में रहते हैं और सामान्य सक्रिय सूचियों से बाहर रखे जाते हैं।
• pinnedAt: वैकल्पिक पिन टाइमस्टैम्प। सक्रिय पिन किए गए सत्र बिना पिन वाले सत्रों से पहले क्रमबद्ध होते हैं; किसी सत्र को संग्रहित करने पर उसका पिन हट जाता है।
• Codex थ्रेड अंतर-संचालन: दोनों फ़ील्ड Codex थ्रेड-प्रबंधन संरचना का अनुसरण करते हैं—वायर पर archived/pinned बूलियन हमेशा टाइमस्टैम्प से व्युत्पन्न होते हैं और सर्वर-साइड पर अंकित किए जाते हैं, जो Codex threads.archived_at अर्थविज्ञान और camelCase क्रमांकन से मेल खाते हैं। OpenClaw टाइमस्टैम्प epoch मिलीसेकंड में होते हैं, जबकि Codex epoch सेकंड का उपयोग करता है, इसलिए ब्रिज codex Plugin सीमा पर रूपांतरण करते हैं। Codex में अभी कोई पिन API नहीं है (केवल thread/archive/thread/unarchive); पिन की स्थिति ऐसा API उपलब्ध होने तक OpenClaw की ओर रहती है, जिसके बाद मेल खाने वाली संरचना आबद्ध सत्रों को पिन स्थिति यांत्रिक रूप से राउंड-ट्रिप करने देती है।
• Codex पर्यवेक्षण केवल गैर-संग्रहित नेटिव थ्रेड सूचीबद्ध करता है। Gateway-स्थानीय idle या notLoaded गतिविधि-अज्ञात थ्रेड को नेटिव thread/archive के माध्यम से केवल तभी संग्रहित किया जा सकता है, जब ऑपरेटर स्पष्ट रूप से पुष्टि करे कि कोई अन्य Codex प्रक्रिया उसकी स्वामी नहीं है; Plugin पहले प्रक्रिया-स्थानीय स्थिति का नया पठन करता है और फिर थ्रेड कैटलॉग से गायब हो जाता है। वह पठन यह सिद्ध नहीं कर सकता कि कोई अन्य App Server प्रक्रिया उस थ्रेड का उपयोग नहीं कर रही है। OpenClaw सक्रिय और त्रुटि वाली पंक्तियों को संग्रहित करने से मना करता है, और युग्मित-Node संग्रह तब तक अनुपलब्ध है जब तक Node ब्रिज पूरे स्ट्रीम किए गए थ्रेड जीवनचक्र का स्वामित्व नहीं ले सकता। किसी नेटिव Codex क्लाइंट में संग्रह से वापस लाने पर थ्रेड फिर से दिखाई देने के योग्य हो जाता है।
• lastReadAt / markedUnreadAt: sessions.patch { unread } द्वारा सर्वर-साइड पर अंकित पठन-स्थिति टाइमस्टैम्प—unread: false पठन दर्ज करता है (lastReadAt सेट करता है, markedUnreadAt हटाता है); unread: true अगले पठन तक सत्र को अपठित चिह्नित करता है। सत्र पंक्तियाँ एक व्युत्पन्न unread बूलियन प्रदर्शित करती हैं: स्पष्ट रूप से अपठित चिह्नित, या नवीनतम गतिविधि से पहले पढ़ा गया। जिन सत्रों को कभी पढ़ा हुआ चिह्नित नहीं किया गया, वे unread: false रहते हैं, इसलिए मौजूदा इंस्टॉलेशन अपग्रेड होने पर सक्रिय नहीं दिखते।
• lastActivityAt: अंतिम पूर्ण हुए एजेंट रन का टाइमस्टैम्प, जिसे अपठित माने जाने योग्य गतिविधि समझा जाता है (उपयोगकर्ता, चैनल और Cron रन)। Heartbeat और आंतरिक-इवेंट टर्न तथा मेटाडेटा पैच इसे अपडेट नहीं करते; updatedAt गतिविधि संकेत नहीं है।
• sessionFile: माइग्रेशन/संग्रह संगतता के लिए रखा गया पुराना मार्कर; सक्रिय रनटाइम SQLite पहचान का उपयोग करता है
• chatType: direct | group | room
• provider, subject, room, space, displayName: समूह/चैनल लेबलिंग मेटाडेटा
• टॉगल: thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel, sendPolicy (प्रति-सत्र ओवरराइड)
• मॉडल चयन: providerOverride, modelOverride, authProfileOverride
• टोकन काउंटर (सर्वोत्तम प्रयास/प्रदाता-निर्भर): inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: इस सत्र कुंजी के लिए स्वतः-Compaction कितनी बार पूर्ण हुआ
• memoryFlushAt / memoryFlushCompactionCount: अंतिम पूर्व-Compaction मेमोरी फ़्लश का टाइमस्टैम्प और Compaction गणना

Gateway प्राधिकार है: सत्र चलने के दौरान यह प्रविष्टियों को फिर से लिख या पुनर्जलित कर सकता है। पुरानी फ़ाइल-समर्थित इंस्टॉलेशन के लिए, sessions.json को संपादित करके रनटाइम से उस फ़ाइल को पढ़ते रहने की अपेक्षा करने के बजाय openclaw doctor --session-sqlite import --session-sqlite-all-agents से माइग्रेट करें।

ट्रांसक्रिप्ट इवेंट संरचना

ट्रांसक्रिप्ट OpenClaw सत्र एक्सेसर द्वारा प्रबंधित किए जाते हैं और पहचान-आधारित सहायकों के माध्यम से रनटाइम कोड के लिए उपलब्ध कराए जाते हैं। इवेंट स्ट्रीम केवल संलग्न करने योग्य है:

• पहली प्रविष्टि: सत्र हेडर—type: "session", id, cwd, timestamp, वैकल्पिक parentSession।
• फिर: id + parentId वाली प्रविष्टियाँ (ट्री संरचना)।

उल्लेखनीय प्रविष्टि प्रकार:

• message: उपयोगकर्ता/सहायक/toolResult संदेश
• custom_message: एक्सटेंशन द्वारा प्रविष्ट कराया गया संदेश, जो मॉडल संदर्भ में प्रवेश करता है (display: true होने पर TUI में रेंडर होता है, display: false होने पर पूरी तरह छिपा रहता है)
• custom: एक्सटेंशन स्थिति, जो मॉडल संदर्भ में प्रवेश नहीं करती (रीलोड के बीच एक्सटेंशन स्थिति बनाए रखने के लिए)
• compaction: firstKeptEntryId और tokensBefore सहित स्थायी Compaction सारांश
• branch_summary: ट्री शाखा में नेविगेट करते समय स्थायी सारांश

OpenClaw जानबूझकर ट्रांसक्रिप्ट को "ठीक" नहीं करता; Gateway उन्हें पढ़ने/लिखने के लिए SessionManager का उपयोग करता है।

संदर्भ विंडो बनाम ट्रैक किए गए टोकन

दो अलग अवधारणाएँ:

1. मॉडल संदर्भ विंडो: प्रति मॉडल कठोर सीमा (मॉडल को दिखाई देने वाले टोकन)। यह मॉडल कैटलॉग से आती है और कॉन्फ़िग के माध्यम से ओवरराइड की जा सकती है।
2. सत्र स्टोर काउंटर: सत्र पंक्ति में लिखे जाने वाले क्रमिक आँकड़े (/status और डैशबोर्ड के लिए प्रयुक्त)। contextTokens एक रनटाइम अनुमान/रिपोर्टिंग मान है—इसे कठोर गारंटी न मानें।

सीमाओं के बारे में अधिक जानकारी: /reference/token-use।

Compaction: यह क्या है

Compaction पुरानी बातचीत को ट्रांसक्रिप्ट में एक स्थायी compaction प्रविष्टि में सारांशित करता है और हाल के संदेश अक्षुण्ण रखता है। Compaction के बाद, भावी टर्न Compaction सारांश तथा firstKeptEntryId के बाद के संदेश देखते हैं। सत्र छँटाई के विपरीत Compaction स्थायी है—/concepts/session-pruning देखें।

एम्बेडेड OpenClaw Compaction डिफ़ॉल्ट रूप से सत्र का विचार स्तर इनहेरिट करता है। सारांश कॉल के लिए अलग स्तर का उपयोग करने हेतु agents.defaults.compaction.thinkingLevel सेट करें; रनटाइम इसे प्रत्येक ठोस Compaction मॉडल या फ़ॉलबैक के अनुसार सीमित करता है। नेटिव Codex app-server Compaction अपने compact अनुरोध का स्वामी होता है और प्रति-Compaction विचार ओवरराइड स्वीकार नहीं कर सकता, इसलिए OpenClaw चेतावनी देता है और वह सेटिंग Codex पर छोड़ देता है।

Compaction के बाद AGENTS.md अनुभाग की पुनः प्रविष्टि agents.defaults.compaction.postCompactionSections के माध्यम से वैकल्पिक बनी रहती है। Plugins before_prompt_build के माध्यम से अन्य प्रॉम्प्ट संदर्भ जोड़ सकते हैं।

खंड सीमाएँ और टूल युग्मन

लंबे ट्रांसक्रिप्ट को Compaction खंडों में विभाजित करते समय, OpenClaw सहायक टूल कॉल को उनकी मेल खाने वाली toolResult प्रविष्टियों के साथ युग्मित रखता है:

• यदि टोकन-अंश विभाजन किसी टूल कॉल और उसके परिणाम के बीच पड़ता, तो OpenClaw युग्म को अलग करने के बजाय सीमा को सहायक के टूल-कॉल संदेश पर स्थानांतरित कर देता है।
• यदि अंतिम टूल-परिणाम ब्लॉक अन्यथा खंड को लक्ष्य से आगे धकेल देता, तो OpenClaw उस लंबित टूल ब्लॉक को सुरक्षित रखता है और असारांशित अंतिम भाग को अक्षुण्ण रखता है।
• निरस्त/त्रुटिपूर्ण टूल-कॉल ब्लॉक लंबित विभाजन को खुला नहीं रखते।

स्वतः-Compaction कब होता है

एम्बेडेड OpenClaw एजेंट में दो ट्रिगर:

1. ओवरफ़्लो पुनर्प्राप्ति: मॉडल संदर्भ-ओवरफ़्लो त्रुटि लौटाता है (request_too_large, context length exceeded, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, ollama error: context length exceeded और प्रदाता-आकार के अन्य प्रकार)—Compaction करें, फिर पुनः प्रयास करें। जब प्रदाता प्रयास किए गए टोकन की संख्या रिपोर्ट करता है, तो OpenClaw उस देखी गई संख्या को ओवरफ़्लो-पुनर्प्राप्ति Compaction में भेजता है; यदि प्रदाता ओवरफ़्लो की पुष्टि करता है लेकिन कोई पार्स करने योग्य संख्या प्रदर्शित नहीं करता, तो OpenClaw Compaction इंजनों और निदान को बजट से न्यूनतम अधिक एक कृत्रिम संख्या भेजता है। यदि ओवरफ़्लो पुनर्प्राप्ति फिर भी विफल होती है, तो OpenClaw वर्तमान सत्र मैपिंग को चुपचाप नई सत्र आईडी में बदलने के बजाय स्पष्ट मार्गदर्शन दिखाता है और उसे सुरक्षित रखता है—संदेश का पुनः प्रयास करें, /compact चलाएँ, या /new चलाएँ।
2. सीमा रखरखाव: सफल टर्न के बाद, जब वर्तमान संदर्भ मॉडल विंडो में से प्रॉम्प्ट और अगले मॉडल आउटपुट के लिए OpenClaw का अंतर्निहित अतिरिक्त स्थान घटाने पर बची सीमा से अधिक हो जाता है।

इन दोनों ट्रिगर के बाहर दो अतिरिक्त सुरक्षा-जाँच चलती हैं:

• प्रीफ़्लाइट स्थानीय Compaction: सक्रिय ट्रांसक्रिप्ट के उस आकार तक पहुँचने पर अगला रन खोलने से पहले स्थानीय Compaction ट्रिगर करने के लिए agents.defaults.compaction.maxActiveTranscriptBytes (बाइट या "20mb" जैसी स्ट्रिंग) सेट करें। यह स्थानीय रूप से दोबारा खोलने की लागत के लिए आकार-सुरक्षा है, अपरिष्कृत संग्रहण नहीं—सामान्य सिमैंटिक Compaction फिर भी चलता है, और इसके लिए truncateAfterCompaction आवश्यक है ताकि संक्षिप्त सारांश एक नया उत्तराधिकारी ट्रांसक्रिप्ट बन जाए।
• मध्य-टर्न पूर्व-जाँच: टूल-लूप सुरक्षा जोड़ने के लिए agents.defaults.compaction.midTurnPrecheck.enabled: true (डिफ़ॉल्ट false) सेट करें। टूल परिणाम जोड़े जाने के बाद और अगले मॉडल कॉल से पहले, OpenClaw उसी प्रीफ़्लाइट बजट तर्क का उपयोग करके प्रॉम्प्ट दबाव का अनुमान लगाता है जो टर्न की शुरुआत में उपयोग होता है। यदि संदर्भ अब फ़िट नहीं होता, तो सुरक्षा इनलाइन Compaction नहीं करती—यह एक संरचित मध्य-टर्न पूर्व-जाँच संकेत उत्पन्न करती है, वर्तमान प्रॉम्प्ट सबमिशन रोकती है, और बाहरी रन लूप को मौजूदा पुनर्प्राप्ति पथ का उपयोग करने देती है (जब पर्याप्त हो तो अत्यधिक बड़े टूल परिणामों को छोटा करना, या कॉन्फ़िगर किया गया Compaction मोड ट्रिगर करके पुनः प्रयास करना)। यह प्रदाता-समर्थित सुरक्षा Compaction सहित default और safeguard दोनों Compaction मोड के साथ काम करती है। maxActiveTranscriptBytes से स्वतंत्र: बाइट-आकार सुरक्षा किसी टर्न के खुलने से पहले चलती है, जबकि मध्य-टर्न पूर्व-जाँच बाद में, नए टूल परिणाम जोड़े जाने के बाद चलती है।

Compaction सेटिंग्स

{  agents: {    defaults: {      compaction: {        enabled: true,        keepRecentTokens: 20000,      },    },  },}

OpenClaw एम्बेडेड रन के लिए एक अंतर्निहित रिज़र्व लागू करता है और उसे सक्रिय मॉडल संदर्भ विंडो के अनुसार सीमित करता है, ताकि वह पूरा प्रॉम्प्ट बजट न खा सके। इससे छोटे-संदर्भ वाले स्थानीय मॉडल पहले टोकन से ही Compaction में जाने से बचते हैं, साथ ही मेमोरी फ़्लश जैसे बहु-टर्न रखरखाव के लिए पर्याप्त अतिरिक्त स्थान बना रहता है।

मैन्युअल /compact स्पष्ट agents.defaults.compaction.keepRecentTokens का पालन करता है और रनटाइम के हालिया-टेल कट बिंदु को बनाए रखता है। स्पष्ट रखरखाव बजट के बिना, मैन्युअल Compaction एक कठोर चेकपॉइंट होता है और पुनर्निर्मित संदर्भ नए सारांश से शुरू होता है।

जब truncateAfterCompaction सक्षम होता है, तो OpenClaw Compaction के बाद सक्रिय ट्रांसक्रिप्ट को संक्षिप्त उत्तराधिकारी में रोटेट करता है। ब्रांच/पुनर्स्थापन चेकपॉइंट क्रियाएँ उस संक्षिप्त उत्तराधिकारी का उपयोग करती हैं; पुराने, Compaction-पूर्व चेकपॉइंट फ़ाइलें संदर्भित रहने तक पढ़ी जा सकती हैं।

प्लग करने योग्य Compaction प्रदाता

Plugins, Plugin API पर registerCompactionProvider() के माध्यम से Compaction प्रदाता पंजीकृत करते हैं। जब agents.defaults.compaction.provider को किसी पंजीकृत प्रदाता आईडी पर सेट किया जाता है, तो सुरक्षा एक्सटेंशन अंतर्निहित summarizeInStages पाइपलाइन के बजाय सारांशीकरण उस प्रदाता को सौंपता है।

• provider: किसी पंजीकृत Compaction प्रदाता Plugin की आईडी। डिफ़ॉल्ट LLM सारांशीकरण के लिए इसे सेट न करें। provider सेट करने से mode: "safeguard" बाध्य होता है।
• प्रदाताओं को अंतर्निहित पथ जैसे ही Compaction निर्देश और पहचानकर्ता-संरक्षण नीति मिलती है, और सुरक्षा प्रदाता आउटपुट के बाद भी हालिया-टर्न तथा विभाजित-टर्न प्रत्यय संदर्भ को सुरक्षित रखती है।
• अंतर्निहित सुरक्षा सारांशीकरण पिछले पूरे सारांश को शब्दशः सुरक्षित रखने के बजाय उसे नए संदेशों के साथ दोबारा परिष्कृत करता है।
• सुरक्षा मोड डिफ़ॉल्ट रूप से सारांश गुणवत्ता ऑडिट सक्षम करता है; विकृत आउटपुट पर पुनः प्रयास का व्यवहार छोड़ने के लिए qualityGuard.enabled: false सेट करें।
• यदि प्रदाता विफल होता है या खाली परिणाम लौटाता है, तो OpenClaw स्वचालित रूप से अंतर्निहित LLM सारांशीकरण पर वापस चला जाता है। कॉलर द्वारा स्पष्ट रूप से ट्रिगर किए गए निरस्तीकरण/टाइमआउट संकेतों को निगला नहीं जाता, बल्कि दोबारा थ्रो किया जाता है, ताकि रद्दीकरण का हमेशा सम्मान हो।

स्रोत: src/plugins/compaction-provider.ts, src/agents/agent-hooks/compaction-safeguard.ts।

उपयोगकर्ता को दिखाई देने वाली सतहें

• किसी भी चैट सत्र में /status
• openclaw status (CLI)
• openclaw sessions / openclaw sessions --json
• Gateway लॉग (pnpm gateway:watch या openclaw logs --follow): embedded run auto-compaction start + complete
• वर्बोज़ मोड: 🧹 Auto-compaction complete तथा Compaction की संख्या

मौन रखरखाव (NO_REPLY)

OpenClaw उन पृष्ठभूमि कार्यों के लिए "मौन" टर्न का समर्थन करता है जिनमें उपयोगकर्ता को मध्यवर्ती आउटपुट नहीं दिखना चाहिए।

• सहायक अपना आउटपुट सटीक मौन टोकन NO_REPLY / no_reply से शुरू करता है, जिसका अर्थ है "उपयोगकर्ता को उत्तर न दें।" OpenClaw डिलीवरी परत में इसे हटा/दबा देता है।
• सटीक मौन-टोकन दमन केस-असंवेदी है: यदि पूरा पेलोड केवल मौन टोकन है, तो NO_REPLY और no_reply दोनों मान्य होते हैं।
• 2026.1.10 से, OpenClaw उस समय ड्राफ़्ट/टाइपिंग स्ट्रीमिंग भी दबाता है जब कोई आंशिक खंड NO_REPLY से शुरू होता है, ताकि मौन संचालन मध्य-टर्न में आंशिक आउटपुट उजागर न करें।
• यह केवल वास्तविक पृष्ठभूमि/बिना-डिलीवरी वाले टर्न के लिए है—यह सामान्य कार्रवाई योग्य उपयोगकर्ता अनुरोधों का शॉर्टकट नहीं है।

Compaction-पूर्व मेमोरी फ़्लश

स्वचालित Compaction होने से पहले, OpenClaw एक मौन एजेंटिक टर्न चला सकता है जो डिस्क पर टिकाऊ स्थिति लिखता है (उदाहरण के लिए, एजेंट कार्यक्षेत्र में memory/YYYY-MM-DD.md), ताकि Compaction महत्वपूर्ण संदर्भ मिटा न सके। यह सत्र संदर्भ उपयोग की निगरानी करता है और Compaction सीमा से नीचे की नरम सीमा पार होते ही सटीक मौन टोकन NO_REPLY / no_reply का उपयोग करते हुए एक मौन "अभी मेमोरी लिखें" निर्देश भेजता है, ताकि उपयोगकर्ता को कुछ दिखाई न दे।

कॉन्फ़िगरेशन (agents.defaults.compaction.memoryFlush), पूरा संदर्भ /gateway/config-agents पर:

टिप्पणियाँ:

• अंतर्निहित प्रॉम्प्ट और सिस्टम प्रॉम्प्ट में डिलीवरी दबाने के लिए NO_REPLY संकेत शामिल होता है।
• जब model सेट होता है, तो फ़्लश टर्न सक्रिय सत्र की फ़ॉलबैक शृंखला इनहेरिट किए बिना उस मॉडल का उपयोग करता है, ताकि केवल-स्थानीय रखरखाव विफलता पर चुपचाप किसी सशुल्क वार्तालाप मॉडल पर फ़ॉलबैक न करे।
• फ़्लश प्रत्येक Compaction चक्र में एक बार चलता है (सत्र पंक्ति में ट्रैक किया जाता है)।
• फ़्लश केवल एम्बेडेड OpenClaw सत्रों के लिए चलता है; CLI बैकएंड और Heartbeat टर्न इसे छोड़ देते हैं।
• सत्र कार्यक्षेत्र केवल-पठन होने पर फ़्लश छोड़ दिया जाता है (workspaceAccess: "ro" या "none")।
• कार्यस्थल फ़ाइल लेआउट और लेखन पैटर्न के लिए मेमोरी देखें।

OpenClaw एक्सटेंशन API में session_before_compact हुक उपलब्ध कराता है, लेकिन ऊपर दिया गया फ़्लश तर्क उस हुक पर नहीं, बल्कि Gateway पक्ष (src/auto-reply/reply/memory-flush.ts, src/auto-reply/reply/agent-runner-memory.ts) पर रहता है।

समस्या निवारण चेकलिस्ट

• सत्र कुंजी गलत है? /concepts/session से शुरू करें और /status में sessionKey की पुष्टि करें।
• स्टोर और ट्रांसक्रिप्ट में असंगति है? openclaw status से Gateway होस्ट और स्टोर पथ की पुष्टि करें।
• बार-बार Compaction हो रहा है? मॉडल की संदर्भ विंडो (बहुत छोटी होने पर बार-बार Compaction बाध्य होता है) और टूल-परिणाम की अधिकता (सत्र प्रूनिंग समायोजित करें) जाँचें।
• छोटे स्थानीय मॉडल पर हर प्रॉम्प्ट ओवरफ़्लो होता दिख रहा है? पुष्टि करें कि प्रदाता सही मॉडल संदर्भ विंडो रिपोर्ट करता है। OpenClaw प्रभावी रिज़र्व को केवल तभी सीमित कर सकता है जब वह विंडो ज्ञात हो।
• मौन टर्न लीक हो रहे हैं? पुष्टि करें कि उत्तर सटीक मौन टोकन NO_REPLY (केस-असंवेदी) से शुरू होता है और आप ऐसे बिल्ड पर हैं जिसमें स्ट्रीमिंग-दमन सुधार (2026.1.10+) शामिल है।

संबंधित

• सत्र प्रबंधन
• सत्र प्रूनिंग
• संदर्भ इंजन
• एजेंट कॉन्फ़िगरेशन संदर्भ