> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

फ़्रेम के आकारों, हैंडशेक, त्रुटियों और संपूर्ण विधि सतह के लिए,
[Gateway प्रोटोकॉल विनिर्देश](https://docs.openclaw.ai/gateway/protocol) पढ़ें।

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
npm install @openclaw/gateway-client @openclaw/gateway-protocol
```

<Note>
  ये पैकेज OpenClaw रिलीज़ शृंखलाओं के साथ वितरित किए जाते हैं। प्रारंभिक रोलआउट के दौरान, पहली पैकेज-युक्त OpenClaw रिलीज़ प्रकाशित होने तक npm
  `E404` लौटा सकता है;
  इन्हें केवल तब इंस्टॉल करें जब नीचे दिए गए रजिस्ट्री पृष्ठ उपलब्ध हों।
</Note>

* [`@openclaw/gateway-protocol`](https://www.npmjs.com/package/@openclaw/gateway-protocol)
  स्कीमा, रनटाइम वैलिडेटर, TypeScript प्रकार, क्लाइंट पहचान और
  क्षमता रजिस्ट्रियाँ, संरचित त्रुटि रीडर तथा प्रोटोकॉल संस्करण स्थिरांक प्रदान करता है।
  इसके npm टारबॉल में जनरेट किया गया
  [`protocol.schema.json`](https://unpkg.com/@openclaw/gateway-protocol/protocol.schema.json)
  मशीन-पठनीय अनुबंध भी शामिल है।
* [`@openclaw/gateway-client`](https://www.npmjs.com/package/@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` जैसे प्रशासनिक कार्यों के लिए जोड़ें।
[ऑपरेटर स्कोप संदर्भ](https://docs.openclaw.ai/gateway/operator-scopes)
संपूर्ण विधि और अनुमोदन-समय के नियम परिभाषित करता है।

`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](https://docs.openclaw.ai/cli/devices) देखें।

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

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

```ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` शामिल हैं।
केवल वही क्षमताएँ घोषित करें जिन्हें क्लाइंट वास्तव में कार्यान्वित करता है।

<Warning>
  `tool-events` लाइव टूल-निष्पादन स्ट्रीमिंग को नियंत्रित करता है। Gateway केवल
  इस क्षमता को घोषित करने वाले कनेक्शनों को किसी रन के संरचित
  टूल इवेंट के प्राप्तकर्ता के रूप में पंजीकृत करता है। इसके बिना कनेक्शन को कोई लाइव टूल इवेंट नहीं मिलता और
  हैंडशेक किसी त्रुटि की सूचना नहीं देता।
</Warning>

क्षमता-नियंत्रित एजेंट टूल उसी घोषणा का एक अलग उपयोग हैं। यदि किसी
एजेंट टूल के लिए क्लाइंट क्षमता आवश्यक है, तो 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` को पोल न करें; उन विधियों को
माँग पर समेकित या विस्तृत रिपोर्ट के लिए सुरक्षित रखें।

## 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 परिवर्तन-सूची](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md)
की समीक्षा करें।

## संबंधित

* [Gateway प्रोटोकॉल](https://docs.openclaw.ai/gateway/protocol)
* [OpenClaw को एम्बेड करना](https://docs.openclaw.ai/gateway/embedding)
* [Gateway RPC संदर्भ](https://docs.openclaw.ai/reference/rpc)
* [बाहरी ऐप्स के लिए Gateway एकीकरण](https://docs.openclaw.ai/gateway/external-apps)