Gateway
Gateway क्लाइंट बनाना
प्रकाशित Gateway पैकेजों का उपयोग ऑपरेटर डैशबोर्ड, WebChat क्लाइंट और अन्य तृतीय-पक्ष एप्लिकेशन बनाने के लिए करें। यह मार्गदर्शिका वायर अनुबंध के आसपास क्लाइंट जीवनचक्र को कवर करती है: प्रमाणीकरण, क्षमताएँ, पुनः कनेक्शन पुनर्प्राप्ति, इतिहास, सदस्यताएँ और संस्करण अपग्रेड।
फ़्रेम के आकार, हैंडशेक, त्रुटियों और संपूर्ण विधि सतह के लिए, Gateway प्रोटोकॉल विनिर्देश पढ़ें।
पैकेज इंस्टॉल करें
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 |
निष्पादन या Plugin अनुमोदनों को सूचीबद्ध करना, प्रदर्शित करना और हल करना |
operator.questions केवल तभी जोड़ें जब क्लाइंट इंटरैक्टिव प्रश्न संभालता हो,
operator.pairing केवल तभी जब वह पेयर किए गए डिवाइस या नोड प्रबंधित करता हो, और
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 से नाम इंपोर्ट करें:
import { GATEWAY_CLIENT_CAPS } from "@openclaw/gateway-protocol/client-info"; 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 को पोल न करें; उन विधियों को
माँग पर समग्र या विस्तृत रिपोर्ट के लिए सुरक्षित रखें।
निष्पादन अनुमोदनों का बैकफ़िल करें
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 परिवर्तन-सूची
की समीक्षा करें।
