बाहरी ऐप्स के लिए Gateway एकीकरण

बाहरी ऐप्स Gateway प्रोटोकॉल के माध्यम से OpenClaw से संवाद करते हैं: WebSocket ट्रांसपोर्ट और RPC विधियाँ। इसका उपयोग तब करें जब कोई स्क्रिप्ट, डैशबोर्ड, CI जॉब, IDE एक्सटेंशन या अन्य प्रक्रिया एजेंट रन शुरू करना, इवेंट स्ट्रीम करना, परिणामों की प्रतीक्षा करना, काम रद्द करना या Gateway संसाधनों का निरीक्षण करना चाहती हो।

npm पैकेज, डिवाइस पेयरिंग, पुनः कनेक्शन रिकवरी, इतिहास, सदस्यताओं और अनुमोदनों के लिए Gateway क्लाइंट बनाना से शुरू करें। यदि आपका ऐप Gateway को चाइल्ड प्रोसेस के रूप में नियंत्रित करता है, तो OpenClaw एम्बेड करना भी पढ़ें। आरंभिक पैकेज रोलआउट के दौरान, पहला पैकेज-सहित OpenClaw रिलीज़ प्रकाशित होने तक npm E404 लौटा सकता है।

यह पृष्ठ OpenClaw प्रक्रिया के बाहर के कोड के लिए है। OpenClaw के भीतर चलने वाले Plugin कोड को इसके बजाय दस्तावेज़ित openclaw/plugin-sdk/* उपपथों का उपयोग करना चाहिए।

आज क्या उपलब्ध है

सतह	स्थिति	इसका उपयोग किसलिए करें
Gateway क्लाइंट गाइड	रिलीज़ शृंखला	npm पैकेज, प्रमाणीकरण, पुनः कनेक्शन, इतिहास, इवेंट, अनुमोदन और संस्करण नीति।
एम्बेडिंग गाइड	रिलीज़ शृंखला	चाइल्ड-प्रोसेस परिवेश, तत्परता, जीवनचक्र, रिकवरी, RPC स्वामित्व और पैकेजिंग।
Gateway प्रोटोकॉल	तैयार	WebSocket ट्रांसपोर्ट, कनेक्ट हैंडशेक, प्रमाणीकरण स्कोप, प्रोटोकॉल संस्करण और इवेंट।
Gateway RPC संदर्भ	तैयार	एजेंट, सत्र, कार्य, मॉडल, टूल, आर्टिफ़ैक्ट और अनुमोदनों के लिए वर्तमान Gateway विधियाँ।
`openclaw agent`	तैयार	जब CLI को शेल से चलाना पर्याप्त हो, तब एकबारगी स्क्रिप्ट एकीकरण।
`openclaw message`	तैयार	स्क्रिप्ट से संदेश या चैनल कार्रवाइयाँ भेजना।

अनुशंसित मार्ग

Gateway चलाएँ या खोजें।
Gateway प्रोटोकॉल के माध्यम से कनेक्ट करें।
Gateway RPC संदर्भ में दस्तावेज़ित RPC विधियों को कॉल करें।
जिस OpenClaw संस्करण के साथ आप परीक्षण करते हैं, उसे पिन करें।
OpenClaw अपग्रेड करते समय RPC संदर्भ दोबारा जाँचें।

एजेंट रन के लिए agent RPC से शुरू करें और टर्मिनल परिणाम के लिए इसे agent.wait के साथ जोड़ें। स्थायी वार्तालाप स्थिति के लिए sessions.* विधियों का उपयोग करें। UI एकीकरणों के लिए Gateway इवेंट की सदस्यता लें और केवल उन्हीं इवेंट परिवारों को रेंडर करें जिन्हें आपका ऐप समझता है।

सहकारी होस्ट निलंबन

चलती प्रक्रिया को फ़्रीज़ या स्नैपशॉट करने वाले होस्टिंग नियंत्रक होस्ट-निरपेक्ष निलंबन हैंडशेक का उपयोग कर सकते हैं:

होस्ट द्वारा नियंत्रित बाहरी इनग्रेस स्वीकार करना बंद करें।
एक स्थिर, अद्वितीय requestId के साथ gateway.suspend.prepare को कॉल करें।
यदि प्रतिक्रिया busy है, तो प्रक्रिया को चालू रखें और बाद में पुनः प्रयास करें।
यदि यह ready है, तो लौटाया गया suspensionId सहेजें, फिर expiresAtMs से पहले प्रक्रिया को फ़्रीज़ या स्नैपशॉट करें।
थॉ होने के बाद, या निलंबन छोड़ दिए जाने पर, मौजूदा WebSocket या Admin HTTP नियंत्रण पथ पर उस suspensionId के साथ gateway.suspend.resume को कॉल करें।

तैयार किया गया Gateway नए WebSocket हैंडशेक अस्वीकार करता है। WebSocket नियंत्रक को होस्ट कार्रवाई के दौरान अपना प्रमाणित कनेक्शन खुला रखना आवश्यक है। यदि इसकी गारंटी नहीं दी जा सकती, तो तैयारी से पहले Admin HTTP RPC Plugin सक्षम करें और उसका उपयोग करें। यदि नियंत्रण पथ खो जाता है, तो पुनः कनेक्ट करने से पहले दो मिनट की लीज़ समाप्त होने की प्रतीक्षा करें; समाप्ति स्वतः प्रवेश फिर से खोल देती है। RPC अनुबंध है:

gateway.suspend.prepare — operator.admin; पैरामीटर { "requestId": "stable-host-operation-id" }
gateway.suspend.status — operator.read; पैरामीटर { "suspensionId": "id-from-prepare" }
gateway.suspend.resume — operator.admin; पैरामीटर { "suspensionId": "id-from-prepare" }

ID के आगे-पीछे के रिक्त स्थान हटाए जाते हैं, उनमें एक गैर-व्हाइटस्पेस वर्ण होना अनिवार्य है और वे 128 वर्णों तक सीमित हैं। व्यस्त तैयारी परिणाम में status: "busy", reason, retryAfterMs, activeCount और blockers होते हैं। तैयार परिणाम का स्वरूप यह है:

{
  "status": "ready",
  "suspensionId": "2c3f...",
  "expiresAtMs": 1770000000000,
  "activeCount": 0,
  "blockers": []
}

स्थिति {"status":"running"} या expiresAtMs सहित तैयार परिणाम लौटाती है। पुनः आरंभ {"ok":true,"status":"running","resumed":true} लौटाता है; सफल पुनः आरंभ के बाद इसे दोहराने पर resumed: false लौटता है। प्रतिस्पर्धी अनुरोध ID या अस्थायी शेड्यूलर-पुनः आरंभ विफलता retryAfterMs सहित पुनः प्रयास योग्य UNAVAILABLE लौटाती है। शेड्यूलर रिकवरी के दौरान तैयारी, स्थिति और पुनः आरंभ सभी वह त्रुटि लौटाते हैं, Gateway तैयार नहीं और विफलता पर बंद रहता है, और होस्ट को उसे फ़्रीज़ या स्नैपशॉट नहीं करना चाहिए। OpenClaw शेड्यूलर का स्वतः पुनः प्रयास करता है और रिकवरी सफल होने के बाद ही प्रवेश फिर से खोलता है। असंगत पुनः आरंभ ID INVALID_REQUEST लौटाती है। तैयारी Gateway के प्रति मिनट तीन प्रयासों वाले नियंत्रण-पटल लेखन बजट को साझा करती है; लौटाई गई पुनः प्रयास देरी का पालन करें। WebSocket क्लाइंट को डिवाइस और IP के अनुसार बकेट किया जाता है। Admin HTTP नियंत्रकों को निर्धारित क्लाइंट IP के अनुसार बकेट किया जाता है, इसलिए एक प्रॉक्सी के पीछे के नियंत्रक एक बजट साझा कर सकते हैं। तैयारी केवल अस्वीकार करने वाली है: OpenClaw नए रूट/सत्र/कमांड प्रवेश को बंद करता है, स्वचालित cron टिक रोकता है और काम का समकालिक रूप से निरीक्षण करता है। यदि कुछ भी सक्रिय है, तो यह busy लौटाने से पहले शेड्यूलर को पुनः आरंभ करता है और प्रवेश फिर से खोलता है; यह उस काम को बाधित या ड्रेन नहीं करता। तैयार लीज़ दो मिनट तक रहती है। समान requestId के साथ prepare दोहराने पर इसका नवीनीकरण होता है; समाप्ति प्रवेश फिर से खोलने से पहले शेड्यूलर को पुनः आरंभ करती है। तैयार लीज़ के दौरान देय होने वाला पुनः आरंभ उत्सर्जन लीज़ के पुनः आरंभ होने तक प्रतीक्षा करता है; प्रगति पर मौजूद पुनः आरंभ के कारण तैयारी busy लौटाती है। तैयार अवस्था में /healthz सक्रिय रहता है और /readyz, 503 लौटाता है। स्थानीय या प्रमाणित तत्परता प्रतिक्रियाओं में gateway-draining शामिल होता है; अप्रमाणित दूरस्थ प्रोब को केवल { "ready": false } मिलता है। HTTP स्वास्थ्य प्रोब, मौजूदा WebSocket कनेक्शन पर निलंबन विधियाँ और पहले से सक्षम Admin HTTP RPC मार्ग उपलब्ध रहते हैं। अन्य RPC पुनः प्रयास योग्य UNAVAILABLE लौटाते हैं। अंतर्निर्मित HTTP उपयोगकर्ता-कार्य मार्ग और सामान्य Plugin HTTP मार्ग, जिनमें OpenAI-संगत API, टूल/सत्र कार्रवाइयाँ, Node वॉच और कॉन्फ़िगर किए गए हुक शामिल हैं, error.code: "gateway_unavailable" के साथ 503 लौटाते हैं। नए Plugin-स्वामित्व वाले WebSocket अपग्रेड भी 503 लौटाते हैं; इसमें अपग्रेड स्वामित्व शामिल है, न कि स्थापित Plugin सॉकेट पर बाद में किया गया काम। यह हैंडशेक आने वाले संदेशों को स्थायी नहीं करता, तृतीय-पक्ष चैनल ट्रांसपोर्ट को नहीं रोकता और होस्टिंग प्लेटफ़ॉर्म को नियंत्रित नहीं करता। होस्ट को तैयारी से पहले अपने इनग्रेस को अवरुद्ध करना आवश्यक है और वेक, स्नैपशॉट/फ़्रीज़ तथा रोकने के लिए वही उत्तरदायी रहता है। activeCount समग्र ट्रैक किए गए काम की संख्या है, जबकि blockers में गैर-शून्य श्रेणी संख्याएँ और सीमित कार्य विवरण होते हैं। यह सामान्य प्रक्रिया-निष्क्रियता अवरोध नहीं है। background-exec अवरोधक केवल समग्र होता है: कमांड टेक्स्ट, प्रक्रिया ID, आउटपुट और सत्र या स्कोप पहचानकर्ता कभी प्रोटोकॉल से नहीं गुजरते। चैनल स्वास्थ्य, रखरखाव, कैश रीफ़्रेश, स्थापित Plugin WebSocket सत्र और अपंजीकृत Plugin-स्वामित्व वाला पृष्ठभूमि कार्य सक्रिय रह सकते हैं। होस्टिंग प्लेटफ़ॉर्म को पूर्ण प्रक्रिया ट्री और उसके फ़ाइल सिस्टम को सुसंगत रूप से फ़्रीज़ या स्नैपशॉट करना आवश्यक है; इस पहले अनुबंध द्वारा अपंजीकृत कार्य का निष्क्रिय होना सिद्ध नहीं किया जा सकता।

होस्ट वेक शेड्यूलिंग के लिए OpenClaw-सामना करने वाले भाग को इन-प्रोसेस Plugin में रखें और आइडेम्पोटेंट पूर्ण स्नैपशॉट को बाहरी होस्ट अडैप्टर पर प्रक्षेपित करें। होस्टिंग नियंत्रक को Plugin SDK आयात नहीं करना चाहिए या इवेंट डेल्टा से cron स्थिति का पुनर्निर्माण नहीं करना चाहिए। सुरक्षित बाहरी cron प्रक्षेपण देखें।

ऐप कोड बनाम Plugin कोड

जब कोड OpenClaw के बाहर हो, तब Gateway RPC का उपयोग करें:

एजेंट रन शुरू करने या देखने वाली Node स्क्रिप्ट
Gateway को कॉल करने वाले CI जॉब
डैशबोर्ड और एडमिन पैनल
IDE एक्सटेंशन
बाहरी ब्रिज जिन्हें चैनल Plugin बनने की आवश्यकता नहीं है
नकली या वास्तविक Gateway ट्रांसपोर्ट वाले एकीकरण परीक्षण

जब कोड OpenClaw के भीतर चलता हो, तब Plugin SDK का उपयोग करें:

प्रदाता Plugin
चैनल Plugin
टूल या जीवनचक्र हुक
एजेंट हार्नेस Plugin
विश्वसनीय रनटाइम सहायक

बाहरी ऐप्स को openclaw/plugin-sdk/* आयात नहीं करना चाहिए; वे उपपथ OpenClaw द्वारा लोड किए गए Plugin के लिए हैं।

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

बाहरी ऐप्स के लिए Gateway एकीकरण

आज क्या उपलब्ध है

अनुशंसित मार्ग

सहकारी होस्ट निलंबन

ऐप कोड बनाम Plugin कोड

संबंधित

​आज क्या उपलब्ध है

​अनुशंसित मार्ग

​सहकारी होस्ट निलंबन

​ऐप कोड बनाम Plugin कोड

​संबंधित

आज क्या उपलब्ध है

अनुशंसित मार्ग

सहकारी होस्ट निलंबन

ऐप कोड बनाम Plugin कोड

संबंधित