RPC and API
बाहरी ऐप्स के लिए Gateway एकीकरण
बाहरी ऐप्स Gateway प्रोटोकॉल के माध्यम से OpenClaw से संवाद करते हैं: WebSocket ट्रांसपोर्ट और RPC विधियाँ। इसका उपयोग तब करें जब कोई स्क्रिप्ट, डैशबोर्ड, CI जॉब, IDE एक्सटेंशन या अन्य प्रक्रिया एजेंट रन शुरू करना, इवेंट स्ट्रीम करना, परिणामों की प्रतीक्षा करना, काम रद्द करना या Gateway संसाधनों का निरीक्षण करना चाहती हो।
आज क्या उपलब्ध है
| सतह | स्थिति | इसका उपयोग किसलिए करें |
|---|---|---|
| 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-स्वामित्व वाला पृष्ठभूमि कार्य
सक्रिय रह सकते हैं।
होस्टिंग प्लेटफ़ॉर्म को पूर्ण प्रक्रिया ट्री और उसके
फ़ाइल सिस्टम को सुसंगत रूप से फ़्रीज़ या स्नैपशॉट करना आवश्यक है; इस पहले
अनुबंध द्वारा अपंजीकृत कार्य का निष्क्रिय होना सिद्ध नहीं किया जा सकता।
ऐप कोड बनाम Plugin कोड
जब कोड OpenClaw के बाहर हो, तब Gateway RPC का उपयोग करें:
- एजेंट रन शुरू करने या देखने वाली Node स्क्रिप्ट
- Gateway को कॉल करने वाले CI जॉब
- डैशबोर्ड और एडमिन पैनल
- IDE एक्सटेंशन
- बाहरी ब्रिज जिन्हें चैनल Plugin बनने की आवश्यकता नहीं है
- नकली या वास्तविक Gateway ट्रांसपोर्ट वाले एकीकरण परीक्षण
जब कोड OpenClaw के भीतर चलता हो, तब Plugin SDK का उपयोग करें:
- प्रदाता Plugin
- चैनल Plugin
- टूल या जीवनचक्र हुक
- एजेंट हार्नेस Plugin
- विश्वसनीय रनटाइम सहायक
बाहरी ऐप्स को openclaw/plugin-sdk/* आयात नहीं करना चाहिए; वे उपपथ
OpenClaw द्वारा लोड किए गए Plugin के लिए हैं।
