Gateway

Gateway क्लाइंट बनाना

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

फ़्रेम के आकारों, हैंडशेक, त्रुटियों और संपूर्ण विधि सतह के लिए, Gateway प्रोटोकॉल विनिर्देश पढ़ें।

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

bash

npm install @openclaw/gateway-client @openclaw/gateway-protocol

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

Node एंट्री अपने WebSocket ट्रांसपोर्ट का प्रबंधन करती है। ब्राउज़र होस्ट डिवाइस पहचान और डिवाइस टोकन के लिए स्थायी स्टोरेज तथा हस्ताक्षर कॉलबैक के साथ एक WebSocket एडाप्टर प्रदान करता है।

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

एक पूर्ण इंटरैक्टिव चैट क्लाइंट, जो अनुमोदन प्रॉम्प्ट भी रेंडर करता है, को इन स्कोप के साथ role: "operator" का अनुरोध करना चाहिए:

स्कोप	इसका उपयोग
`operator.read`	`chat.history`, `sessions.list`, `sessions.subscribe`, मॉडल स्थिति और केवल-पढ़ने योग्य इवेंट
`operator.write`	`chat.send` और सामान्य सत्र परिवर्तन
`operator.approvals`	exec या Plugin अनुमोदनों को सूचीबद्ध करना, प्रदर्शित करना और हल करना

operator.questions केवल तभी जोड़ें जब क्लाइंट इंटरैक्टिव प्रश्नों को संभालता हो, operator.pairing केवल तभी जब वह पेयर किए गए डिवाइस या Node प्रबंधित करता हो, और operator.admin केवल config.patch जैसे प्रशासनिक कार्यों के लिए जोड़ें। ऑपरेटर स्कोप संदर्भ संपूर्ण विधि और अनुमोदन-समय के नियम परिभाषित करता है।

openclaw.json को हाथ से संपादित करके प्रति-क्लाइंट बियरर टोकन न बनाएँ। Gateway के साझा बूटस्ट्रैप प्रमाणीकरण को openclaw configure --section gateway या openclaw onboard --gateway-auth ... विकल्पों से कॉन्फ़िगर करें, फिर डिवाइस पेयरिंग को क्लाइंट टोकन जारी करने दें:

क्लाइंट में Ed25519 डिवाइस पहचान स्थायी रूप से सहेजें।
connect.challenge की प्रतीक्षा करें, चुनौती-बद्ध डिवाइस पेलोड पर हस्ताक्षर करें और अनुरोधित ऑपरेटर भूमिका, स्कोप तथा बूटस्ट्रैप प्रमाणीकरण के लिए साझा Gateway टोकन या पासवर्ड के साथ connect भेजें।
यदि Gateway संरचित PAIRING_REQUIRED विवरण लौटाता है, तो अनुरोध ID दिखाएँ और error.details.recommendedNextStep के अनुसार रोकें या पुनः प्रयास करें।
Gateway होस्ट पर openclaw devices list से अनुरोध की समीक्षा करें, फिर उसी सटीक वर्तमान अनुरोध को openclaw devices approve <requestId> से अनुमोदित करें।
पुनः कनेक्ट करें और समझौते से तय भूमिका तथा स्कोप के साथ hello-ok.auth.deviceToken स्थायी रूप से सहेजें। बाद के कनेक्शनों के लिए उस डिवाइस टोकन का उपयोग करें।

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

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

connect.params.caps उस वैकल्पिक व्यवहार का वर्णन करता है जिसका क्लाइंट उपयोग कर सकता है। यह प्राधिकरण प्रदान नहीं करता। स्ट्रिंग लिटरल दोहराने के बजाय GATEWAY_CLIENT_CAPS से नाम इंपोर्ट करें:

 const caps = [GATEWAY_CLIENT_CAPS.TOOL_EVENTS];

वर्तमान रजिस्ट्री में approvals, exec-approvals, inline-widgets, run-tool-bindings, session-scoped-events, plugin-approvals, task-suggestions, terminal-offset-seq, tool-events और ui-commands शामिल हैं। केवल वही क्षमताएँ घोषित करें जिन्हें क्लाइंट वास्तव में कार्यान्वित करता है।

क्षमता-नियंत्रित एजेंट टूल उसी घोषणा का एक अलग उपयोग हैं। यदि किसी एजेंट टूल के लिए क्लाइंट क्षमता आवश्यक है, तो Gateway उस टूल को तब तक शामिल नहीं करता जब तक आरंभकर्ता क्लाइंट ने प्रत्येक आवश्यक क्षमता घोषित न की हो।

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

प्रत्येक सफल पुनः कनेक्शन को स्थायी इतिहास और वर्तमान इन-मेमोरी रन स्थिति पर एक नए प्रोजेक्शन के रूप में मानें:

sessions.subscribe और चयनित सत्र की sessions.messages.subscribe सदस्यता पुनः स्थापित करें।
चयनित sessionKey के लिए chat.history कॉल करें और स्थानीय रूप से स्थायी पंक्तियों को लौटाए गए messages प्रोजेक्शन से बदलें।
यदि inFlightRun मौजूद है, तो उसके runId, बफ़र किए गए text और वैकल्पिक plan को अपनाएँ। text खाली होने पर भी रन अपनाएँ।
sessionInfo.hasActiveRun और sessionInfo.activeRunIds पढ़ें। यह तय करते समय कि कोई बनाए रखा गया रन अब भी स्ट्रीमिंग UI का स्वामी है या नहीं, activeRunIds में सटीक सदस्यता को प्राथमिकता दें। बिना किसी सूचीबद्ध ID वाला सत्य hasActiveRun किसी अन्य सक्रिय रनटाइम प्रोजेक्शन को दर्शा सकता है।
बाद के 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 को पोल न करें; उन विधियों को माँग पर समेकित या विस्तृत रिपोर्ट के लिए सुरक्षित रखें।

exec अनुमोदनों का बैकफ़िल करें

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

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

वर्तमान वायर संस्करण 4 है। सामान्य ऑपरेटर और WebChat क्लाइंट को minProtocol: 4 और maxProtocol: 4 के साथ सटीक वर्तमान संस्करण पर समझौता करना होगा। केवल प्रमाणीकृत Node क्लाइंट और हल्के प्रोब के पास N-1 स्वीकृति विंडो है, जो वर्तमान में प्रोटोकॉल 3 से 4 तक है।

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