Skip to main content
प्रकाशित Gateway पैकेजों का उपयोग ऑपरेटर डैशबोर्ड, WebChat क्लाइंट और अन्य तृतीय-पक्ष एप्लिकेशन बनाने के लिए करें। यह मार्गदर्शिका वायर अनुबंध के आसपास क्लाइंट जीवनचक्र को कवर करती है: प्रमाणीकरण, क्षमताएँ, पुनः कनेक्शन पुनर्प्राप्ति, इतिहास, सदस्यताएँ और संस्करण अपग्रेड। फ़्रेम के आकार, हैंडशेक, त्रुटियों और संपूर्ण विधि सतह के लिए, Gateway प्रोटोकॉल विनिर्देश पढ़ें।

​
पैकेज इंस्टॉल करें

ये पैकेज OpenClaw रिलीज़ शृंखलाओं के साथ भेजे जाते हैं। प्रारंभिक रोलआउट के दौरान, पहली पैकेज-युक्त OpenClaw रिलीज़ प्रकाशित होने तक npm E404 लौटा सकता है; इन्हें केवल तब इंस्टॉल करें जब नीचे दिए गए रजिस्ट्री पृष्ठ उपलब्ध हों।
  • @openclaw/gateway-protocol स्कीमा, रनटाइम वैलिडेटर, TypeScript प्रकार, क्लाइंट पहचान और क्षमता रजिस्ट्रियाँ, संरचित त्रुटि रीडर तथा प्रोटोकॉल संस्करण स्थिरांक प्रदान करता है। इसके npm टारबॉल में जनरेट किया गया protocol.schema.json मशीन-पठनीय अनुबंध भी शामिल है।
  • @openclaw/gateway-client संदर्भ कनेक्शन कार्यान्वयन है। Node क्लाइंट के लिए पैकेज रूट और ब्राउज़र-सुरक्षित प्रोटोकॉल, डिवाइस प्रमाणीकरण तथा पुनः कनेक्शन सहायकों के लिए @openclaw/gateway-client/browser इंपोर्ट करें।
Node एंट्री अपने WebSocket ट्रांसपोर्ट का स्वामित्व रखती है। ब्राउज़र होस्ट डिवाइस पहचान और डिवाइस टोकन के लिए WebSocket अडैप्टर के साथ स्थायी स्टोरेज और हस्ताक्षर कॉलबैक प्रदान करता है।

​
स्कोप चुनें और डिवाइस पेयर करें

अनुमोदन प्रॉम्प्ट भी रेंडर करने वाले पूर्ण इंटरैक्टिव चैट क्लाइंट को इन स्कोप के साथ role: "operator" का अनुरोध करना चाहिए: operator.questions केवल तभी जोड़ें जब क्लाइंट इंटरैक्टिव प्रश्न संभालता हो, operator.pairing केवल तभी जब वह पेयर किए गए डिवाइस या नोड प्रबंधित करता हो, और operator.admin केवल config.patch जैसे प्रशासनिक कार्यों के लिए जोड़ें। ऑपरेटर स्कोप संदर्भ संपूर्ण विधि और अनुमोदन-समय के नियम परिभाषित करता है। openclaw.json को हाथ से संपादित करके प्रति-क्लाइंट बेयरर टोकन न बनाएँ। Gateway के साझा बूटस्ट्रैप प्रमाणीकरण को openclaw configure --section gateway या openclaw onboard --gateway-auth ... विकल्पों से कॉन्फ़िगर करें, फिर डिवाइस पेयरिंग को क्लाइंट टोकन बनाने दें:
  1. क्लाइंट में Ed25519 डिवाइस पहचान स्थायी रूप से संग्रहीत करें।
  2. connect.challenge की प्रतीक्षा करें, चैलेंज-बाउंड डिवाइस पेलोड पर हस्ताक्षर करें और अनुरोधित ऑपरेटर भूमिका, स्कोप तथा बूटस्ट्रैप प्रमाणीकरण के लिए साझा Gateway टोकन या पासवर्ड के साथ connect भेजें।
  3. यदि Gateway संरचित PAIRING_REQUIRED विवरण लौटाता है, तो अनुरोध ID दिखाएँ और error.details.recommendedNextStep के अनुसार रोकें या पुनः प्रयास करें।
  4. Gateway होस्ट पर openclaw devices list से अनुरोध की समीक्षा करें, फिर उसी वर्तमान अनुरोध को openclaw devices approve <requestId> से अनुमोदित करें।
  5. पुनः कनेक्ट करें और तय की गई भूमिका तथा स्कोप के साथ hello-ok.auth.deviceToken को स्थायी रूप से संग्रहीत करें। बाद के कनेक्शन के लिए उसी डिवाइस टोकन का उपयोग करें।
स्कोप या भूमिका अपग्रेड एक नया लंबित पेयरिंग अनुरोध बनाते हैं। टोकन रोटेशन अनुमोदित पेयरिंग अनुबंध का विस्तार नहीं कर सकता। अनुमोदन, रोटेशन और निरस्तीकरण कमांड के लिए डिवाइस CLI देखें।

​
क्लाइंट क्षमताएँ घोषित करें

connect.params.caps ऐसे वैकल्पिक व्यवहार का वर्णन करता है जिसका क्लाइंट उपयोग कर सकता है। यह प्राधिकरण प्रदान नहीं करता। स्ट्रिंग लिटरल दोहराने के बजाय GATEWAY_CLIENT_CAPS से नाम इंपोर्ट करें:
वर्तमान रजिस्ट्री में approvals, exec-approvals, inline-widgets, run-tool-bindings, session-scoped-events, plugin-approvals, task-suggestions, terminal-offset-seq, tool-events और ui-commands शामिल हैं। केवल उन्हीं क्षमताओं को घोषित करें जिन्हें क्लाइंट वास्तव में लागू करता है।
tool-events लाइव टूल-निष्पादन स्ट्रीमिंग को नियंत्रित करता है। Gateway केवल इस क्षमता को घोषित करने वाले कनेक्शन को किसी रन के संरचित टूल इवेंट के प्राप्तकर्ता के रूप में पंजीकृत करता है। इसके बिना, कनेक्शन को कोई लाइव टूल इवेंट नहीं मिलता और हैंडशेक किसी त्रुटि की सूचना नहीं देता।
क्षमता-नियंत्रित एजेंट टूल इसी घोषणा का एक अलग उपयोग हैं। यदि किसी एजेंट टूल को क्लाइंट क्षमता की आवश्यकता है, तो Gateway उस टूल को तब तक शामिल नहीं करता जब तक आरंभकर्ता क्लाइंट ने प्रत्येक आवश्यक क्षमता घोषित न की हो।

​
पुनः कनेक्शन के बाद स्थिति पुनर्प्राप्त करें

प्रत्येक सफल पुनः कनेक्शन को स्थायी इतिहास और वर्तमान इन-मेमोरी रन स्थिति पर एक नया प्रोजेक्शन मानें:
  1. sessions.subscribe और चयनित सत्र की sessions.messages.subscribe सदस्यता फिर से स्थापित करें।
  2. चयनित sessionKey के लिए chat.history कॉल करें और स्थानीय रूप से स्थायी पंक्तियों को लौटाए गए messages प्रोजेक्शन से बदलें।
  3. यदि inFlightRun मौजूद है, तो उसका runId, बफ़र किया गया text और वैकल्पिक plan अपनाएँ। text खाली होने पर भी रन को अपनाएँ।
  4. sessionInfo.hasActiveRun और sessionInfo.activeRunIds पढ़ें। यह तय करते समय कि बनाए रखा गया रन अब भी स्ट्रीमिंग UI का स्वामी है या नहीं, activeRunIds में सटीक सदस्यता को प्राथमिकता दें। सूचीबद्ध ID के बिना सत्य hasActiveRun किसी अन्य सक्रिय रनटाइम प्रोजेक्शन को दर्शा सकता है।
  5. बाद के agent इवेंट को payload.runId और payload.seq के अनुसार समन्वित करें। प्रत्येक रन के लिए उच्चतम स्वीकृत अनुक्रम स्वतंत्र रूप से बनाए रखें, पहले से देखे गए या कम अनुक्रम को अनदेखा करें और आगे के अंतराल को आधिकारिक इतिहास फिर से लोड करने का कारण मानें।
बाहरी इवेंट फ़्रेम में वैकल्पिक seq भी होता है, जो वर्तमान WebSocket कनेक्शन पर इवेंट को क्रमबद्ध करता है। यह नए कनेक्शन के साथ रीसेट हो जाता है। किसी agent इवेंट पेलोड के भीतर का seq प्रति रन निर्दिष्ट होता है और उस रन के जीवनचक्र, असिस्टेंट, योजना, टूल तथा अन्य स्ट्रीम इवेंट को क्रमबद्ध करता है।

​
इतिहास मेटाडेटा और स्थिर एंकर का उपयोग करें

chat.history द्वारा लौटाई गई पंक्तियों में __openclaw मेटाडेटा एनवलप हो सकता है:
  • id ट्रांसक्रिप्ट एंट्री की पहचान है। एंकर किए गए इतिहास अनुरोधों के लिए इसका उपयोग करें, लेकिन अद्वितीय प्रदर्शन-पंक्ति कुंजी के रूप में नहीं।
  • seq धनात्मक ट्रांसक्रिप्ट-रिकॉर्ड अनुक्रम है। एक संग्रहीत रिकॉर्ड एक से अधिक प्रदर्शन पंक्तियों में प्रोजेक्ट हो सकता है, इसलिए समान id और अनुक्रम वाले संबंधित तत्वों को साथ रखें।
  • kind सिंथेटिक पंक्तियों की पहचान करता है। Compaction सीमा kind: "compaction" का उपयोग करती है और यदि किसी मेल खाते चेकपॉइंट ने वे मेट्रिक रिकॉर्ड किए हों, तो tokensBefore तथा tokensAfter शामिल कर सकती है।
प्रतिक्रिया के hasMore और nextOffset मानों से पीछे की ओर पृष्ठांकन करें। संख्यात्मक ऑफ़सेट वर्तमान ट्रांसक्रिप्ट प्रोजेक्शन का वर्णन करते हैं, इसलिए उन्हें रीसेट या Compaction के पार दीर्घकालिक बुकमार्क के रूप में स्थायी रूप से संग्रहीत न करें। इसके बजाय __openclaw.id स्थायी रूप से संग्रहीत करें। ज्ञात पंक्ति के आसपास पुनर्स्थापित करने के लिए messageId और उसे लौटाने वाले sessionId के साथ chat.history कॉल करें। Gateway रीसेट संग्रह इतिहास से उस एंकर को हल कर सकता है; एंकर की गई प्रतिक्रियाएँ जानबूझकर संख्यात्मक पृष्ठांकन मेटाडेटा छोड़ देती हैं।

​
उपयोग को पोल करने के बजाय सदस्यता लें

प्रारंभिक कैटलॉग को sessions.list से लोड करें, फिर प्रति कनेक्शन एक बार sessions.subscribe कॉल करें। sessions.changed इवेंट को sessionKey के अनुसार मर्ज करें। सत्र परिवर्तन पेलोड में लाइव inputTokens, outputTokens, totalTokens, totalTokensFresh, contextTokens, estimatedCostUsd, प्रतिक्रिया-उपयोग सेटिंग और सक्रिय-रन स्थिति हो सकती है। कुछ परिवर्तन सूचनाएँ केवल अमान्यकरण संकेत होती हैं। यदि कोई इवेंट आपके दृश्य के लिए आवश्यक पंक्ति फ़ील्ड छोड़ देता है, तो sessions.list रीफ़्रेश करें। लाइव सत्र सूची को अद्यतन रखने के लिए usage.cost या sessions.usage को पोल न करें; उन विधियों को माँग पर समग्र या विस्तृत रिपोर्ट के लिए सुरक्षित रखें।

​
निष्पादन अनुमोदनों का बैकफ़िल करें

operator.approvals वाले क्लाइंट को hello-ok पूरा होते ही अपना इवेंट लिसनर इंस्टॉल करना चाहिए, फिर कनेक्शन से पहले के अनुरोध बैकफ़िल करने के लिए exec.approval.list कॉल करना चाहिए। सूची और लाइव exec.approval.requested / exec.approval.resolved इवेंट को अनुमोदन ID के अनुसार समन्वित करें, ताकि सूची अनुरोध के साथ प्रतिस्पर्धा करने वाला संक्रमण न तो खोए और न पुनर्जीवित हो।

​
प्रोटोकॉल संस्करण ट्रैक करें

वर्तमान वायर संस्करण 4 है। सामान्य ऑपरेटर और WebChat क्लाइंट को minProtocol: 4 और maxProtocol: 4 के साथ सटीक वर्तमान संस्करण तय करना आवश्यक है। केवल प्रमाणित नोड क्लाइंट और हल्के प्रोब के पास N-1 स्वीकृति विंडो है, जो वर्तमान में प्रोटोकॉल 3 से 4 तक है। प्रोटोकॉल परिवर्तन पहले योगात्मक होते हैं। protocol.schema.json में since रिलीज़-काल मेटाडेटा और मुख्य विधियों के लिए आवश्यक स्कोप मेटाडेटा शामिल है, लेकिन वायर संस्करण वृद्धि फिर भी तृतीय-पक्ष क्लाइंट के लिए एक स्पष्ट ब्रेकिंग इवेंट है। परीक्षण किए गए पैकेज संस्करणों को पिन करें, वायर संस्करण बदलने पर क्लाइंट और Gateway को साथ में अपग्रेड करें और प्रत्येक अपग्रेड से पहले OpenClaw परिवर्तन-सूची की समीक्षा करें।

​
संबंधित