सत्र प्रबंधन का गहन अध्ययन

एकल Gateway प्रक्रिया सत्र स्थिति का शुरू से अंत तक स्वामित्व रखती है। UIs (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 द्वारा नहीं, जो केवल संग्रह आर्टिफ़ैक्ट की आयु निर्धारित करता है। स्पष्ट विलोपन अलग है: यह हटाए गए सत्र की पंक्तियाँ निकालने से पहले संपीड़ित ट्रांसक्रिप्ट संग्रह (*.jsonl.deleted.<timestamp>.zst, जब zstd उपलब्ध हो) लिखता और सत्यापित करता है।

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, hooks, 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> सत्र प्रविष्टि को स्वच्छ करता है: यह सुरक्षित प्राथमिकताएँ (thinking/fast/verbose/reasoning सेटिंग्स, लेबल, प्रदर्शन नाम) और स्पष्ट उपयोगकर्ता-चयनित मॉडल/auth ओवरराइड आगे ले जाता है, लेकिन परिवेशी वार्तालाप संदर्भ (चैनल/समूह रूटिंग, भेजने/कतार नीति, एलिवेशन, मूल, 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); इसके उपलब्ध होने तक पिन की गई स्थिति 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 अपने कॉम्पैक्ट अनुरोध का स्वामी होता है और प्रति-Compaction चिंतन ओवरराइड स्वीकार नहीं कर सकता, इसलिए OpenClaw चेतावनी देता है और उस सेटिंग को Codex पर छोड़ देता है।

Compaction के बाद AGENTS.md अनुभाग का पुनः-इंजेक्शन agents.defaults.compaction.postCompactionSections के माध्यम से ऑप्ट-इन है; सेट न होने या [] होने पर, OpenClaw Compaction सारांश के ऊपर AGENTS.md अंश नहीं जोड़ता।

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

किसी लंबी ट्रांसक्रिप्ट को 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 से, यदि कोई आंशिक चंक NO_REPLY से शुरू होता है, तो OpenClaw ड्राफ़्ट/टाइपिंग स्ट्रीमिंग को भी दबाता है, ताकि मौन संचालन मध्य-टर्न में आंशिक आउटपुट उजागर न करें।
• यह केवल वास्तविक पृष्ठभूमि/बिना-डिलीवरी वाले टर्न के लिए है—यह सामान्य कार्रवाई योग्य उपयोगकर्ता अनुरोधों का शॉर्टकट नहीं है।

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+) शामिल है।

संबंधित

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