Node पेयरिंग

Node पेयरिंग की दो परतें हैं, और दोनों युग्मित डिवाइस रिकॉर्ड में Gateway के SQLite स्टेट डेटाबेस में संग्रहीत होती हैं:

• डिवाइस पेयरिंग (भूमिका node) connect हैंडशेक को नियंत्रित करती है। नीचे विश्वसनीय-CIDR डिवाइस स्वतः-अनुमोदन और चैनल पेयरिंग देखें।
• Node क्षमता अनुमोदन (node.pair.*) यह नियंत्रित करता है कि कनेक्टेड Node किन घोषित क्षमताओं/कमांड को उपलब्ध करा सकता है। Gateway सत्य का स्रोत है; UI (macOS ऐप, Control UI) ऐसे फ़्रंटएंड हैं जो लंबित अनुरोधों को अनुमोदित या अस्वीकार करते हैं।

पूर्व स्वतंत्र Node पेयरिंग स्टोर (nodes/paired.json, जिसमें प्रत्येक Node के लिए टोकन था और जिसे जनवरी 2026 में कनेक्ट पथ से हटा दिया गया था) अब समाप्त हो चुका है: Gateway स्टार्टअप पर एक बार बची हुई सभी पंक्तियों को डिवाइस रिकॉर्ड में समाहित करते हैं और लीगेसी फ़ाइलों को .migrated प्रत्यय के साथ संग्रहित करते हैं। लीगेसी TCP ब्रिज समर्थन हटा दिया गया है।

क्षमता अनुमोदन कैसे काम करता है

1. एक Node Gateway WS से कनेक्ट होता है (डिवाइस पेयरिंग इस चरण को नियंत्रित करती है)।
2. Gateway घोषित क्षमता/कमांड सतह की तुलना अनुमोदित सतह से करता है; नई या विस्तृत सतहें डिवाइस रिकॉर्ड पर एक लंबित अनुरोध संग्रहीत करती हैं और node.pair.requested उत्सर्जित करती हैं।
3. आप अनुरोध को अनुमोदित या अस्वीकार करते हैं (CLI या UI)।
4. अनुमोदन तक Node कमांड फ़िल्टर किए रहते हैं; अनुमोदन सामान्य कमांड नीति के अधीन घोषित सतह उपलब्ध कराता है।

लंबित अनुरोध Node के अंतिम पुनः प्रयास के 5 मिनट बाद स्वतः समाप्त हो जाते हैं — सक्रिय रूप से पुनः कनेक्ट होने वाला Node प्रत्येक प्रयास पर नया अनुरोध (और अनुमोदन संकेत) बनाने के बजाय अपने एक लंबित अनुरोध को सक्रिय रखता है।

CLI कार्यप्रवाह (हेडलेस-अनुकूल)

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status युग्मित/कनेक्टेड Node और उनकी क्षमताएँ दिखाता है।

API सतह (Gateway प्रोटोकॉल)

इवेंट:

• node.pair.requested - नया लंबित अनुरोध बनने पर उत्सर्जित होता है।
• node.pair.resolved - अनुरोध अनुमोदित, अस्वीकृत या समाप्त होने पर उत्सर्जित होता है।

विधियाँ:

• node.pair.list - लंबित और युग्मित Node की सूची देता है (operator.pairing)।
• node.pair.approve - लंबित अनुरोध को अनुमोदित करता है।
• node.pair.reject - लंबित अनुरोध को अस्वीकार करता है।
• node.pair.remove - युग्मित Node हटाता है। यह युग्मित-डिवाइस स्टोर में डिवाइस की node भूमिका रद्द करता है, उसके साथ अनुमोदित Node सतह हटाता है, और उस डिवाइस के Node-भूमिका सत्रों को अमान्य/डिस्कनेक्ट करता है। मिश्रित-भूमिका वाला डिवाइस (उदाहरण के लिए, जिसके पास operator भी है) अपनी पंक्ति बनाए रखता है और केवल node भूमिका खोता है; केवल-Node डिवाइस की पंक्ति हटा दी जाती है। प्राधिकरण: operator.pairing गैर-ऑपरेटर Node पंक्तियाँ हटा सकता है; मिश्रित-भूमिका डिवाइस पर अपनी स्वयं की Node भूमिका रद्द करने वाले डिवाइस-टोकन कॉलर को अतिरिक्त रूप से operator.admin चाहिए।
• node.rename - युग्मित Node के ऑपरेटर-दृश्य डिस्प्ले नाम को बदलता है।

2026.7 में हटाए गए: node.pair.request और node.pair.verify। लंबित अनुरोध Node कनेक्शन के दौरान स्वयं Gateway बनाता है, और जिस स्वतंत्र प्रति-Node टोकन के लिए वे काम करते थे वह अब मौजूद नहीं है; Node प्रमाणीकरण डिवाइस पेयरिंग टोकन है।

टिप्पणियाँ:

• अपरिवर्तित सतह के साथ पुनः कनेक्शन लंबित अनुरोध का पुनः उपयोग करते हैं; बार-बार किए गए अनुरोध संग्रहीत Node मेटाडेटा और ऑपरेटर दृश्यता के लिए नवीनतम अनुमत-सूचीबद्ध घोषित कमांड स्नैपशॉट को रीफ़्रेश करते हैं।
• ऑपरेटर स्कोप स्तरों और अनुमोदन-समय जाँचों का सारांश ऑपरेटर स्कोप में दिया गया है।
• node.pair.approve अतिरिक्त अनुमोदन स्कोप लागू करने के लिए लंबित अनुरोध के घोषित कमांड का उपयोग करता है:
  • कमांड-रहित अनुरोध: operator.pairing
  • सामान्य कमांड अनुरोध: operator.pairing + operator.write
  • system.run, system.run.prepare, system.which, browser.proxy, fs.listDir, या system.execApprovals.get/set वाला एडमिन-संवेदनशील अनुरोध: operator.pairing + operator.admin

Node कमांड नियंत्रण (2026.3.31+)

जब कोई Node पहली बार कनेक्ट होता है, तो पेयरिंग का अनुरोध स्वतः किया जाता है। जब तक वह अनुरोध अनुमोदित नहीं होता, उस Node के सभी लंबित Node कमांड फ़िल्टर किए जाते हैं और निष्पादित नहीं होंगे। पेयरिंग अनुमोदित होने के बाद, Node के घोषित कमांड सामान्य कमांड नीति के अधीन उपलब्ध हो जाते हैं।

इसका अर्थ है:

• जो Node पहले कमांड उपलब्ध कराने के लिए केवल डिवाइस पेयरिंग पर निर्भर थे, उन्हें अब Node पेयरिंग भी पूरी करनी होगी।
• पेयरिंग अनुमोदन से पहले कतारबद्ध कमांड स्थगित नहीं, बल्कि हटा दिए जाते हैं।

Node इवेंट की विश्वास सीमाएँ (2026.3.31+)

Node से शुरू किए गए सारांश और संबंधित सत्र इवेंट इच्छित विश्वसनीय सतह तक सीमित हैं। सूचना-संचालित या Node-ट्रिगर किए गए प्रवाह, जो पहले व्यापक होस्ट या सत्र टूल पहुँच पर निर्भर थे, उनमें समायोजन की आवश्यकता हो सकती है। यह सुदृढ़ीकरण Node इवेंट को Node की विश्वास सीमा द्वारा अनुमत सीमा से बाहर होस्ट-स्तरीय टूल पहुँच तक अधिकार बढ़ाने से रोकता है।

स्थायी Node उपस्थिति अपडेट समान पहचान सीमा का पालन करते हैं: node.presence.alive इवेंट केवल प्रमाणित Node डिवाइस सत्रों से स्वीकार किया जाता है और पेयरिंग मेटाडेटा केवल तभी अपडेट करता है जब डिवाइस/Node पहचान पहले से युग्मित हो। स्वयं घोषित client.id मान अंतिम-देखी गई स्थिति लिखने के लिए पर्याप्त नहीं है।

SSH-सत्यापित डिवाइस स्वतः-अनुमोदन (डिफ़ॉल्ट)

निजी/CGNAT पते से पहली बार होने वाली role: node डिवाइस पेयरिंग तब स्वतः अनुमोदित होती है, जब Gateway SSH के माध्यम से मशीन का स्वामित्व सिद्ध कर सकता है: यह पेयरिंग होस्ट (BatchMode, StrictHostKeyChecking=yes) से वापस कनेक्ट होता है, वहाँ openclaw node identity --json चलाता है, और केवल तभी अनुमोदित करता है जब रिमोट डिवाइस आईडी और सार्वजनिक कुंजी लंबित अनुरोध से पूरी तरह मेल खाते हैं। कुंजी का मिलान ही इसे सुरक्षित बनाता है: केवल पहुँच-योग्यता कभी अनुमोदन नहीं करती, इसलिए NAT सह-निवासी, साझा होस्ट के अन्य उपयोगकर्ता और LAN स्पूफ़िंग सभी सामान्य संकेत प्रवाह पर लौटते हैं।

डिफ़ॉल्ट रूप से सक्षम। इसके सक्रिय होने की आवश्यकताएँ:

• Gateway प्रक्रिया उपयोगकर्ता (या sshVerify.user) Node होस्ट पर गैर-संवादात्मक रूप से SSH कर सकता है (कुंजियाँ/एजेंट; Tailscale SSH भी काम करता है), और होस्ट कुंजी पहले से विश्वसनीय है।
• openclaw गैर-संवादात्मक sh -lc के लिए रिमोट PATH पर हल हो जाता है।
• कनेक्ट होने वाला IP प्रत्यक्ष (गैर-प्रॉक्सी, गैर-लूपबैक) निजी, ULA, लिंक-लोकल या CGNAT पता है, या सेट होने पर sshVerify.cidrs से मेल खाता है।
• विश्वसनीय-CIDR अनुमोदन के समान पात्रता आधार: केवल नई, स्कोप-रहित Node पेयरिंग; अपग्रेड, ब्राउज़र, Control UI और WebChat हमेशा संकेत दिखाते हैं।

जाँच चलने के दौरान Node क्लाइंट को मैन्युअल अनुमोदन के लिए रुकने के बजाय पुनः प्रयास करते रहने (wait_then_retry) के लिए कहा जाता है; यदि जाँच विफल हो जाती है, तो अगला प्रयास सामान्य संकेत प्रवाह पर लौटता है। विफल लक्ष्य एक छोटी कूलडाउन अवधि पाते हैं (कुंजी बेमेल होने के बाद 5 मिनट)।

अनुमोदित डिवाइस approvedVia: "ssh-verified" रिकॉर्ड करते हैं और उनकी पहली घोषित क्षमता सतह उसी चरण में अनुमोदित हो जाती है — कुंजी मिलान पहले ही सिद्ध कर देता है कि Node ऑपरेटर के खाते के अंतर्गत उनकी अपनी मशीन पर चल रहा है, जो वही दावा है जिसे मैन्युअल क्षमता अनुमोदन पुष्ट करता है। बाद के सतह अपग्रेड पर फिर भी संकेत दिखता है।

सुदृढ़ करें या अक्षम करें:

{  gateway: {    nodes: {      pairing: {        // पूरी तरह अक्षम करें:        sshVerify: false,        // ...या जाँच का स्कोप/समायोजन निर्धारित करें:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

स्वतः-अनुमोदन (macOS ऐप)

macOS ऐप Node क्षमता अनुरोधों के मौन अनुमोदन का प्रयास कर सकता है जब:

• अनुरोध को silent चिह्नित किया गया हो (जब डिवाइस पेयरिंग गैर-संवादात्मक रूप से अनुमोदित हुई हो, तो Gateway पहली क्षमता सतह को मौन चिह्नित करता है), और
• ऐप उसी उपयोगकर्ता का उपयोग करके Gateway होस्ट से SSH कनेक्शन सत्यापित कर सके।

यदि मौन अनुमोदन विफल होता है, तो यह सामान्य Approve/Reject संकेत पर लौट जाता है।

विश्वसनीय-CIDR डिवाइस स्वतः-अनुमोदन

role: node के लिए WS डिवाइस पेयरिंग डिफ़ॉल्ट रूप से मैन्युअल रहती है। निजी Node नेटवर्क में, जहाँ Gateway पहले से नेटवर्क पथ पर विश्वास करता है, ऑपरेटर स्पष्ट CIDR या सटीक IP के साथ इसे वैकल्पिक रूप से सक्षम कर सकते हैं:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

सुरक्षा सीमा:

• gateway.nodes.pairing.autoApproveCidrs सेट न होने पर अक्षम।
• कोई व्यापक LAN या निजी-नेटवर्क स्वतः-अनुमोदन मोड मौजूद नहीं है; SSH-सत्यापित स्वतः-अनुमोदन (ऊपर) के लिए क्रिप्टोग्राफ़िक डिवाइस-कुंजी मिलान आवश्यक है, केवल नेटवर्क निकटता कभी पर्याप्त नहीं होती।
• केवल बिना अनुरोधित स्कोप वाला नया role: node डिवाइस पेयरिंग अनुरोध पात्र है।
• ऑपरेटर, ब्राउज़र, Control UI और WebChat क्लाइंट मैन्युअल रहते हैं।
• भूमिका, स्कोप, मेटाडेटा और सार्वजनिक-कुंजी अपग्रेड मैन्युअल रहते हैं।
• समान-होस्ट लूपबैक विश्वसनीय-प्रॉक्सी हेडर पथ पात्र नहीं हैं, क्योंकि उस पथ को स्थानीय कॉलर द्वारा स्पूफ़ किया जा सकता है।

मौन पेयरिंग प्रतिस्थापन सफ़ाई

गैर-संवादात्मक अनुमोदन युग्मित-डिवाइस पंक्ति पर अपना उद्गम रिकॉर्ड करते हैं: समान-होस्ट स्थानीय नीति अनुमोदन silent के रूप में, विश्वसनीय-CIDR Node अनुमोदन trusted-cidr के रूप में और SSH-सत्यापित Node अनुमोदन ssh-verified के रूप में। जिन क्लाइंट की स्टेट डायरेक्टरी अस्थायी है (अस्थायी होम, कंटेनर, प्रति-रन सैंडबॉक्स), वे प्रत्येक रन में नई डिवाइस कुंजी-जोड़ी बनाते हैं, और प्रत्येक रन एक बिलकुल नए डिवाइस के रूप में मौन रूप से फिर से पेयर होता है — सफ़ाई के बिना युग्मित सूची हर रन में एक बासी पंक्ति से बढ़ती है।

जब Gateway किसी स्थानीय डिवाइस पेयरिंग को मौन रूप से अनुमोदित करता है, तो वह उसी क्लाइंट क्लस्टर से संबंधित पुराने silent-अनुमोदित रिकॉर्ड को सेवानिवृत्त करता है (जो clientId, clientMode और डिस्प्ले नाम से मेल खाते हैं) और वर्तमान में कनेक्टेड नहीं हैं। स्थानीय क्लाइंट स्वयं Gateway होस्ट पर चलते हैं, इसलिए क्लस्टर कुंजी किसी दूसरी मशीन से मेल नहीं खा सकती। सेवानिवृत्त पंक्तियाँ तुरंत अपने टोकन खो देती हैं; किसी भी मेल खाती लीगेसी Node पेयरिंग प्रविष्टि को साफ़ कर दिया जाता है और node.pair.resolved हटाने का इवेंट प्रसारित किया जाता है।

सीमाएँ:

• केवल वे रिकॉर्ड पात्र हैं जिनका नवीनतम अनुमोदन उसी होस्ट पर स्थानीय (silent) था, ट्रिगर और लक्ष्य दोनों के रूप में। विश्वसनीय-CIDR और SSH-सत्यापित पेयरिंग उन होस्ट के बीच होती हैं जहाँ प्रदर्शन मेटाडेटा मशीन की पहचान नहीं है, इसलिए उन्हें कभी भी स्वचालित रूप से नहीं हटाया जाता — उनके लिए Control UI क्लीनअप या openclaw nodes remove का उपयोग करें।
• स्वामी द्वारा अनुमोदित और QR/सेटअप-कोड (बूटस्ट्रैप) पेयरिंग कभी भी स्वचालित रूप से नहीं हटाई जातीं। उद्गम-जानकारी उपलब्ध होने से पहले अनुमोदित रिकॉर्ड सुरक्षित रहते हैं, उसी डिवाइस आईडी के बाद में हुए मूक पुनः-अनुमोदन के बाद भी।
• वर्तमान में कनेक्टेड डिवाइस छोड़ दिए जाते हैं, ताकि अलग-अलग स्थिति डायरेक्टरी वाले समवर्ती स्थानीय सत्र लाइव रहने के दौरान अपने टोकन बनाए रखें। पिछले एक मिनट में अनुमोदित रिकॉर्ड भी छोड़ दिए जाते हैं, ताकि एक साथ होने वाले पेयरिंग हैंडशेक अपने कनेक्शन पंजीकृत होने से पहले एक-दूसरे को निष्क्रिय न कर सकें।
• प्रभावित क्लाइंट संरचना के अनुसार स्थानीय होते हैं, इसलिए वे अपने अगले कनेक्शन पर चुपचाप फिर से पेयर हो जाते हैं।

मेटाडेटा-अपग्रेड का स्वचालित अनुमोदन

जब पहले से पेयर किया गया डिवाइस केवल गैर-संवेदनशील मेटाडेटा परिवर्तनों (उदाहरण के लिए प्रदर्शन नाम या क्लाइंट प्लेटफ़ॉर्म संकेत) के साथ फिर से कनेक्ट होता है, तो OpenClaw इसे metadata-upgrade मानता है। मूक स्वचालित अनुमोदन का दायरा सीमित है: यह केवल विश्वसनीय गैर-ब्राउज़र स्थानीय पुनः-कनेक्शन पर लागू होता है, जो पहले ही स्थानीय या साझा क्रेडेंशियल के अधिकार को प्रमाणित कर चुके हैं, जिसमें OS संस्करण मेटाडेटा बदलने के बाद उसी होस्ट पर नेटिव ऐप के पुनः-कनेक्शन शामिल हैं। ब्राउज़र/Control UI क्लाइंट और रिमोट क्लाइंट अब भी स्पष्ट पुनः-अनुमोदन प्रवाह का उपयोग करते हैं। दायरा अपग्रेड (रीड से राइट/एडमिन) और सार्वजनिक कुंजी परिवर्तन मेटाडेटा-अपग्रेड स्वचालित अनुमोदन के लिए पात्र नहीं हैं; वे स्पष्ट पुनः-अनुमोदन अनुरोध बने रहते हैं।

QR पेयरिंग सहायक

/pair qr पेयरिंग पेलोड को संरचित मीडिया के रूप में रेंडर करता है, ताकि मोबाइल और ब्राउज़र क्लाइंट उसे सीधे स्कैन कर सकें।

किसी डिवाइस को हटाने पर उस डिवाइस आईडी के सभी पुराने लंबित पेयरिंग अनुरोध भी हटा दिए जाते हैं, ताकि निरस्तीकरण के बाद nodes pending अनाथ पंक्तियाँ न दिखाए।

स्थानीयता और फ़ॉरवर्ड किए गए हेडर

Gateway पेयरिंग किसी कनेक्शन को केवल तभी लूपबैक मानती है, जब रॉ सॉकेट और अपस्ट्रीम प्रॉक्सी के सभी प्रमाण सहमत हों। यदि कोई अनुरोध लूपबैक पर आता है, लेकिन उसमें Forwarded, कोई भी X-Forwarded-*, या X-Real-IP हेडर प्रमाण मौजूद है, तो वह फ़ॉरवर्डेड-हेडर प्रमाण लूपबैक स्थानीयता के दावे को अमान्य कर देता है, और पेयरिंग पथ अनुरोध को उसी होस्ट का कनेक्शन मानकर चुपचाप स्वीकार करने के बजाय स्पष्ट अनुमोदन आवश्यक करता है। ऑपरेटर प्रमाणीकरण पर समान नियम के लिए विश्वसनीय प्रॉक्सी प्रमाणीकरण देखें।

संग्रहण (स्थानीय, निजी)

पेयरिंग स्थिति, Gateway स्थिति डायरेक्टरी के अंतर्गत साझा SQLite स्थिति डेटाबेस में पेयर किए गए डिवाइस रिकॉर्ड पर रहती है (डिफ़ॉल्ट ~/.openclaw):

• ~/.openclaw/state/openclaw.sqlite (डिवाइस प्रमाणीकरण वाले पेयर किए गए डिवाइस, अनुमोदित Node सतहें, लंबित सतह अनुरोध, लंबित डिवाइस पेयरिंग अनुरोध और बूटस्ट्रैप टोकन)

यदि आप OPENCLAW_STATE_DIR को ओवरराइड करते हैं, तो डेटाबेस भी उसके साथ स्थानांतरित हो जाता है। JSON स्टोर वाली रिलीज़ से अपग्रेड किए गए Gateway उन्हें स्टार्टअप पर आयात करते हैं और devices/*.json.migrated तथा nodes/*.json.migrated अभिलेख पीछे छोड़ देते हैं।

सुरक्षा संबंधी टिप्पणियाँ:

• डिवाइस टोकन गोपनीय जानकारी हैं; स्थिति डेटाबेस को संवेदनशील मानें।
• डिवाइस टोकन को रोटेट करने के लिए openclaw devices rotate / device.token.rotate का उपयोग होता है।

ट्रांसपोर्ट व्यवहार

• ट्रांसपोर्ट स्थितिरहित है; यह सदस्यता संग्रहीत नहीं करता।
• यदि Gateway ऑफ़लाइन है या पेयरिंग अक्षम है, तो Node पेयर नहीं कर सकते।
• रिमोट मोड में, पेयरिंग रिमोट Gateway के स्टोर के विरुद्ध होती है।

संबंधित

• चैनल पेयरिंग
• Node CLI
• डिवाइस CLI