Fundamentals

एजेंट लूप

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

प्रवेश बिंदु

Gateway RPC: agent और agent.wait।
CLI: openclaw agent।

रन क्रम

agent RPC पैरामीटर सत्यापित करता है, सत्र (sessionKey/sessionId) का समाधान करता है, सत्र मेटाडेटा सहेजता है, और तुरंत { runId, acceptedAt } लौटाता है।
agentCommand टर्न चलाता है: मॉडल + चिंतन/विस्तृत/ट्रेस डिफ़ॉल्ट का समाधान करता है, Skills स्नैपशॉट लोड करता है, runEmbeddedAgent को कॉल करता है, और यदि एम्बेडेड लूप ने पहले से ऐसा कोई उत्सर्जन नहीं किया है, तो फ़ॉलबैक जीवनचक्र समाप्ति/त्रुटि उत्सर्जित करता है।
runEmbeddedAgent: प्रति-सत्र और वैश्विक कतारों के माध्यम से रन क्रमबद्ध करता है, मॉडल + प्रमाणीकरण प्रोफ़ाइल का समाधान करता है, OpenClaw सत्र बनाता है, रनटाइम इवेंट की सदस्यता लेता है, सहायक/टूल डेल्टा स्ट्रीम करता है, रन टाइमआउट लागू करता है (समाप्ति पर निरस्त करके), और उपयोग मेटाडेटा के साथ पेलोड लौटाता है। Codex ऐप-सर्वर टर्न के लिए, यह ऐसे स्वीकृत टर्न को भी निरस्त करता है जो टर्मिनल इवेंट से पहले ऐप-सर्वर प्रगति उत्पन्न करना बंद कर देता है।
subscribeEmbeddedAgentSession रनटाइम इवेंट को agent स्ट्रीम से जोड़ता है: टूल इवेंट को stream: "tool", सहायक डेल्टा को stream: "assistant", जीवनचक्र इवेंट को stream: "lifecycle" (phase: "start" | "end" | "error")।
agent.wait (waitForAgentRun) किसी runId पर जीवनचक्र समाप्ति/त्रुटि की प्रतीक्षा करता है और { status: ok|error|timeout, startedAt, endedAt, error? } लौटाता है।

कतारबद्धता और समवर्तीता

रन प्रति सत्र कुंजी (सत्र लेन) क्रमबद्ध होते हैं और वैकल्पिक रूप से वैश्विक लेन से होकर गुजरते हैं, जिससे टूल/सत्र रेस रोकी जाती हैं। संदेश चैनल एक कतार मोड (steer/followup/collect/interrupt) चुनते हैं, जो इस लेन प्रणाली को इनपुट देता है; कमांड कतार देखें।

ट्रांसक्रिप्ट लेखन को सत्र फ़ाइल पर सत्र लेखन लॉक द्वारा अतिरिक्त सुरक्षा दी जाती है। लॉक प्रक्रिया-जागरूक और फ़ाइल-आधारित है, इसलिए यह उन लेखकों को भी पकड़ता है जो प्रक्रिया-अंतर्गत कतार को बायपास करते हैं या किसी अन्य प्रक्रिया से आते हैं। सत्र को व्यस्त बताए जाने से पहले लेखक डिफ़ॉल्ट रूप से अधिकतम 60 सेकंड प्रतीक्षा करते हैं (एन्वायरमेंट ओवरराइड OPENCLAW_SESSION_WRITE_LOCK_ACQUIRE_TIMEOUT_MS)।

सत्र लेखन लॉक डिफ़ॉल्ट रूप से पुनःप्रवेशी नहीं होते। एक ही तार्किक लेखक को बनाए रखते हुए जानबूझकर उसी लॉक के अधिग्रहण को नेस्ट करने वाले हेल्पर को allowReentrant: true के साथ ऑप्ट इन करना होगा।

सत्र और कार्यक्षेत्र की तैयारी

कार्यस्थल का समाधान करके उसे बनाया जाता है; सैंडबॉक्स किए गए रन को सैंडबॉक्स कार्यस्थल रूट पर पुनर्निर्देशित किया जा सकता है।
Skills लोड किए जाते हैं (या स्नैपशॉट से पुनः उपयोग किए जाते हैं) और एन्वायरमेंट तथा प्रॉम्प्ट में अंतःक्षेपित किए जाते हैं।
बूटस्ट्रैप/संदर्भ फ़ाइलों का समाधान करके उन्हें सिस्टम प्रॉम्प्ट में अंतःक्षेपित किया जाता है।
स्ट्रीमिंग शुरू होने से पहले सत्र लेखन लॉक अधिग्रहित किया जाता है और सत्र ट्रांसक्रिप्ट लक्ष्य तैयार किया जाता है। बाद में ट्रांसक्रिप्ट को पुनः लिखने, Compaction करने या छोटा करने वाले किसी भी पथ को SQLite ट्रांसक्रिप्ट पंक्तियों में बदलाव करने से पहले यही लॉक लेना होगा।

प्रॉम्प्ट संयोजन

सिस्टम प्रॉम्प्ट OpenClaw के आधार प्रॉम्प्ट, Skills प्रॉम्प्ट, बूटस्ट्रैप संदर्भ और प्रति-रन ओवरराइड से बनाया जाता है। मॉडल-विशिष्ट सीमाएँ और Compaction आरक्षित टोकन लागू किए जाते हैं। मॉडल क्या देखता है, इसके लिए सिस्टम प्रॉम्प्ट देखें।

हुक

OpenClaw में दो हुक प्रणालियाँ हैं:

आंतरिक हुक (Gateway हुक): कमांड और जीवनचक्र इवेंट के लिए इवेंट-संचालित स्क्रिप्ट।
Plugin हुक: एजेंट/टूल जीवनचक्र और Gateway पाइपलाइन के भीतर विस्तार बिंदु।

आंतरिक हुक (Gateway हुक)

agent:bootstrap: सिस्टम प्रॉम्प्ट को अंतिम रूप दिए जाने से पहले बूटस्ट्रैप फ़ाइलें बनाते समय चलता है। बूटस्ट्रैप संदर्भ फ़ाइलें जोड़ने या हटाने के लिए इसका उपयोग करें।
कमांड हुक: /new, /reset, /stop, और अन्य कमांड इवेंट (हुक दस्तावेज़ देखें)।

सेटअप और उदाहरणों के लिए हुक देखें।

Plugin हुक

ये एजेंट लूप या Gateway पाइपलाइन के भीतर चलते हैं:

हुक	कब चलता है
`before_model_resolve`	पूर्व-सत्र (`messages` के बिना), समाधान से पहले प्रदाता/मॉडल को नियतात्मक रूप से ओवरराइड करने के लिए।
`before_prompt_build`	सत्र लोड होने के बाद (`messages` के साथ), प्रस्तुति से पहले `prependContext`, `systemPrompt`, `prependSystemContext`, या `appendSystemContext` अंतःक्षेपित करने के लिए। प्रति-टर्न गतिशील टेक्स्ट के लिए `prependContext` और सिस्टम प्रॉम्प्ट स्थान में आने वाले स्थिर मार्गदर्शन के लिए सिस्टम-संदर्भ फ़ील्ड का उपयोग करें।
`before_agent_reply`	इनलाइन कार्रवाइयों के बाद, LLM कॉल से पहले। किसी Plugin को टर्न ग्रहण करके कृत्रिम उत्तर लौटाने या उसे पूरी तरह मौन करने देता है।
`agent_end`	पूर्णता के बाद, अंतिम संदेश सूची और रन मेटाडेटा के साथ।
`before_compaction` / `after_compaction`	Compaction चक्रों का अवलोकन या उन पर टिप्पणी करता है।
`before_tool_call` / `after_tool_call`	टूल पैरामीटर/परिणामों को इंटरसेप्ट करता है।
`before_install`	ऑपरेटर स्थापना नीति चलने के बाद, चरणबद्ध skill/Plugin स्थापना सामग्री पर, जब Plugin हुक वर्तमान प्रक्रिया में लोड हों।
`tool_result_persist`	टूल परिणामों को OpenClaw के स्वामित्व वाले सत्र ट्रांसक्रिप्ट में लिखे जाने से पहले समकालिक रूप से रूपांतरित करता है।
`message_received` / `message_sending` / `message_sent`	आवक और जावक संदेश हुक।
`session_start` / `session_end`	सत्र जीवनचक्र सीमाएँ।
`gateway_start` / `gateway_stop`	Gateway जीवनचक्र इवेंट।

जावक/टूल गार्ड के लिए हुक निर्णय नियम:

before_tool_call: { block: true } अंतिम है और कम-प्राथमिकता वाले हैंडलर को रोकता है। { block: false } कोई कार्रवाई नहीं करता और किसी पिछले ब्लॉक को साफ़ नहीं करता।
before_install: ऊपर जैसे ही अंतिम/कोई-कार्रवाई-नहीं अर्थ। ऑपरेटर-स्वामित्व वाले स्थापना अनुमति/अवरोध निर्णयों, जिन्हें CLI स्थापना और अपडेट पथों को शामिल करना आवश्यक है, के लिए before_install नहीं, बल्कि security.installPolicy का उपयोग करें।
message_sending: { cancel: true } अंतिम है और कम-प्राथमिकता वाले हैंडलर को रोकता है। { cancel: false } कोई कार्रवाई नहीं करता और किसी पिछले निरस्तीकरण को साफ़ नहीं करता।

हुक API और पंजीकरण विवरण के लिए Plugin हुक देखें।

हार्नेस इन हुक को अनुकूलित कर सकते हैं। Codex ऐप-सर्वर हार्नेस दस्तावेज़ीकृत प्रतिबिंबित सतहों के लिए OpenClaw Plugin हुक को संगतता अनुबंध के रूप में बनाए रखता है; Codex मूल हुक एक अलग, निम्न-स्तरीय Codex तंत्र हैं।

स्ट्रीमिंग

सहायक डेल्टा एजेंट रनटाइम से assistant इवेंट के रूप में स्ट्रीम होते हैं।
ब्लॉक स्ट्रीमिंग text_end या message_end पर आंशिक उत्तर उत्सर्जित कर सकती है।
रीज़निंग स्ट्रीमिंग एक अलग स्ट्रीम हो सकती है या उत्तरों को अवरुद्ध कर सकती है।
खंडीकरण और ब्लॉक उत्तर व्यवहार के लिए स्ट्रीमिंग देखें।

टूल निष्पादन

टूल आरंभ/अपडेट/समाप्ति इवेंट tool स्ट्रीम पर उत्सर्जित होते हैं।
लॉगिंग/उत्सर्जन से पहले टूल परिणामों का आकार और छवि पेलोड के लिए शोधन किया जाता है।
डुप्लिकेट सहायक पुष्टियों को रोकने के लिए संदेश टूल प्रेषण ट्रैक किए जाते हैं।

उत्तर का स्वरूप निर्धारण

अंतिम पेलोड सहायक टेक्स्ट (साथ में वैकल्पिक रीज़निंग), इनलाइन टूल सारांश (जब विस्तृत मोड चालू हो और अनुमति हो), और मॉडल में त्रुटि होने पर सहायक त्रुटि टेक्स्ट से संयोजित किए जाते हैं।

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

Compaction और पुनः प्रयास

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

इवेंट स्ट्रीम

lifecycle: subscribeEmbeddedAgentSession द्वारा उत्सर्जित (और फ़ॉलबैक के रूप में agentCommand द्वारा)।
assistant: एजेंट रनटाइम से स्ट्रीम किए गए डेल्टा।
tool: एजेंट रनटाइम से स्ट्रीम किए गए टूल इवेंट।

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

चैट चैनल प्रबंधन

सहायक डेल्टा चैट delta संदेशों में बफ़र होते हैं। जीवनचक्र समाप्ति/त्रुटि पर चैट final उत्सर्जित होता है।

टाइमआउट

समय-समाप्ति	डिफ़ॉल्ट	टिप्पणियाँ
`agent.wait`	30s	केवल प्रतीक्षा; `timeoutMs` पैरामीटर इसे ओवरराइड करता है। यह अंतर्निहित रन को नहीं रोकता।
एजेंट रनटाइम (`agents.defaults.timeoutSeconds`)	172800s (48h)	`runEmbeddedAgent` के निरस्तीकरण टाइमर द्वारा लागू। असीमित रन बजट के लिए `0` सेट करें; मॉडल स्ट्रीम की सक्रियता पर नज़र रखने वाले वॉचडॉग फिर भी लागू रहते हैं।
CLI बैकएंड आउटपुट-रहित वॉचडॉग	प्रत्येक नए/फिर से शुरू किए गए CLI रन के लिए गणना की जाती है	एजेंट रनटाइम से अलग और पंजीकृत बैकएंड Plugin के स्वामित्व में। CLI का आंतरिक बैकग्राउंड कार्य पैरेंट सबप्रोसेस साझा करता है और समग्र एजेंट समय-समाप्ति के बाद जारी नहीं रहता।
Cron पृथक एजेंट टर्न	Cron के स्वामित्व में	निष्पादन शुरू होने पर शेड्यूलर अपना टाइमर शुरू करता है, कॉन्फ़िगर की गई समय-सीमा पर रन निरस्त करता है, फिर समय-समाप्ति दर्ज करने से पहले सीमित क्लीनअप चलाता है, ताकि कोई पुराना चाइल्ड सेशन लेन को अटका न रख सके।
मॉडल निष्क्रियता समय-समाप्ति	क्लाउड 120s; स्वयं-होस्टेड 300s	निष्क्रियता अवधि से पहले कोई प्रतिक्रिया खंड न आने पर OpenClaw मॉडल अनुरोध निरस्त कर देता है। `models.providers.<id>.timeoutSeconds` धीमे स्थानीय/स्वयं-होस्टेड प्रदाताओं के लिए इस निष्क्रियता वॉचडॉग की अवधि बढ़ाता है, लेकिन यह किसी भी कम परिमित `agents.defaults.timeoutSeconds` या रन-विशिष्ट समय-समाप्ति से सीमित रहता है, क्योंकि वे पूरे एजेंट रन को नियंत्रित करते हैं। असीमित रन बजट में भी प्रदाता-वर्ग निष्क्रियता वॉचडॉग बना रहता है। बिना स्पष्ट मॉडल/एजेंट समय-समाप्ति वाले Cron-ट्रिगर किए गए क्लाउड मॉडल रन में यही डिफ़ॉल्ट लागू होता है; स्पष्ट Cron रन समय-समाप्ति होने पर, क्लाउड मॉडल स्ट्रीम का ठहराव अधिकतम 60s होता है, ताकि कॉन्फ़िगर किए गए मॉडल फ़ॉलबैक बाहरी Cron समय-सीमा से पहले फिर भी चल सकें। वास्तविक स्थानीय एंडपॉइंट (लूपबैक/निजी baseUrl) पर Cron-ट्रिगर किए गए रन स्थानीय निष्क्रियता ऑप्ट-आउट बनाए रखते हैं; नेटवर्क baseUrls पर स्वयं-होस्टेड प्रदाताओं को अंतर्निहित 300s वॉचडॉग मिलता है। स्पष्ट Cron रन समय-समाप्ति होने पर, स्थानीय/स्वयं-होस्टेड ठहराव अधिकतम उसी समय-समाप्ति तक सीमित रहता है। धीमे स्थानीय प्रदाताओं के लिए `models.providers.<id>.timeoutSeconds` सेट करें।
प्रदाता HTTP अनुरोध समय-समाप्ति	`models.providers.<id>.timeoutSeconds`	उस प्रदाता के लिए कनेक्शन, हेडर, बॉडी, SDK अनुरोध समय-समाप्ति, सुरक्षित-fetch निरस्तीकरण प्रबंधन और मॉडल स्ट्रीम निष्क्रियता वॉचडॉग को कवर करता है। पूरे एजेंट रनटाइम की समय-समाप्ति बढ़ाने से पहले धीमे स्थानीय/स्वयं-होस्टेड प्रदाताओं (उदाहरण के लिए Ollama) के लिए इसका उपयोग करें; जब मॉडल अनुरोध को अधिक समय तक चलना हो, तो एजेंट/रनटाइम समय-समाप्ति को कम-से-कम उतना ही रखें।

अटके हुए सेशन का निदान

निदान सक्षम होने पर, अंतर्निहित दो-मिनट की सीमा ऐसे लंबे processing सेशन को वर्गीकृत करती है जिनमें कोई प्रतिक्रिया, टूल, स्थिति, अवरोध या ACP प्रगति नहीं देखी गई है:

सक्रिय एम्बेडेड रन, मॉडल कॉल और टूल कॉल को session.long_running के रूप में रिपोर्ट किया जाता है। स्वामित्व वाली मौन मॉडल कॉल निरस्तीकरण सीमा तक session.long_running बनी रहती हैं, ताकि धीमे या गैर-स्ट्रीमिंग प्रदाताओं को बहुत जल्दी रुका हुआ न माना जाए।
हाल की प्रगति के बिना सक्रिय कार्य को session.stalled के रूप में रिपोर्ट किया जाता है। स्वामित्व वाली मॉडल कॉल निरस्तीकरण सीमा पर या उसके बाद session.stalled में बदल जाती हैं; स्वामी-रहित पुरानी मॉडल/टूल गतिविधि को लंबे समय से चल रही गतिविधि के रूप में छिपाया नहीं जाता।
session.stuck पुनर्प्राप्त किए जा सकने वाले पुराने सेशन रिकॉर्ड-रखरखाव के लिए आरक्षित है, जिसमें पुरानी स्वामी-रहित मॉडल/टूल गतिविधि वाले निष्क्रिय कतारबद्ध सेशन शामिल हैं।

निरस्तीकरण सीमा कम-से-कम 5 मिनट और चेतावनी सीमा की 3x होती है। पुनर्प्राप्ति जाँच सफल होते ही पुराना सेशन रिकॉर्ड-रखरखाव प्रभावित सेशन लेन को तुरंत मुक्त कर देता है; रुके हुए एम्बेडेड रन केवल निरस्तीकरण सीमा के बाद ही निरस्त करके निकाले जाते हैं, ताकि कतारबद्ध कार्य केवल धीमे रन को बीच में रोके बिना फिर से शुरू हो सके। पुनर्प्राप्ति संरचित अनुरोधित/पूर्ण परिणाम उत्सर्जित करती है; निदान स्थिति को केवल तभी निष्क्रिय चिह्नित किया जाता है जब वही प्रसंस्करण पीढ़ी अभी भी वर्तमान हो, और सेशन के अपरिवर्तित रहने तक बार-बार होने वाले session.stuck निदान के बीच का अंतराल बढ़ता जाता है।

कार्य समय से पहले कहाँ समाप्त हो सकते हैं

एजेंट समय-समाप्ति (निरस्तीकरण)
AbortSignal (रद्द करना)
Gateway डिस्कनेक्शन या RPC समय-समाप्ति
agent.wait समय-समाप्ति (केवल प्रतीक्षा, एजेंट को नहीं रोकती)