डिस्कवरी और ट्रांसपोर्ट्स¶

OpenClaw में दो अलग-अलग समस्याएँ हैं जो सतह पर समान दिखती हैं:

1. ऑपरेटर रिमोट कंट्रोल: macOS मेनू बार ऐप जो कहीं और चल रहे Gateway को नियंत्रित करता है।
2. नोड पेयरिंग: iOS/Android (और भविष्य के नोड्स) का Gateway को ढूँढना और सुरक्षित रूप से पेयर करना।

डिज़ाइन लक्ष्य यह है कि सभी नेटवर्क डिस्कवरी/विज्ञापन को Node Gateway (openclaw gateway) में रखा जाए और क्लाइंट्स (mac ऐप, iOS) को उपभोक्ता के रूप में रखा जाए।

शर्तें¶

• Gateway: एक सिंगल लंबे समय तक चलने वाली गेटवे प्रोसेस जो स्टेट (सेशंस, पेयरिंग, नोड रजिस्ट्री) की मालिक होती है और चैनल्स चलाती है। अधिकांश सेटअप्स प्रति होस्ट एक का उपयोग करते हैं; आइसोलेटेड मल्टी-गेटवे सेटअप्स संभव हैं।
• Gateway WS (control plane): 127.0.0.1:18789 पर डिफ़ॉल्ट WebSocket एंडपॉइंट; gateway.bind के माध्यम से LAN/tailnet पर बाइंड किया जा सकता है।
• Direct WS transport: LAN/tailnet-फेसिंग Gateway WS एंडपॉइंट (SSH नहीं)।
• SSH transport (fallback): SSH के माध्यम से 127.0.0.1:18789 को फ़ॉरवर्ड करके रिमोट कंट्रोल।
• Legacy TCP bridge (deprecated/removed): पुराना नोड ट्रांसपोर्ट (देखें Bridge protocol); अब डिस्कवरी के लिए विज्ञापित नहीं।

प्रोटोकॉल विवरण:

• Gateway प्रोटोकॉल
• ब्रिज प्रोटोकॉल (लीगेसी)

हम “direct” और SSH दोनों क्यों रखते हैं¶

• Direct WS समान नेटवर्क और tailnet के भीतर सर्वोत्तम UX देता है:
• Bonjour के माध्यम से LAN पर ऑटो-डिस्कवरी
• Gateway द्वारा स्वामित्व वाले पेयरिंग टोकन + ACLs
• शेल एक्सेस की आवश्यकता नहीं; प्रोटोकॉल सतह कसी हुई और ऑडिट योग्य रहती है
• SSH सार्वभौमिक फ़ॉलबैक बना रहता है:
• जहाँ भी SSH एक्सेस हो वहाँ काम करता है (असंबंधित नेटवर्क्स के पार भी)
• मल्टीकास्ट/mDNS समस्याओं से अप्रभावित
• SSH के अलावा किसी नए इनबाउंड पोर्ट की आवश्यकता नहीं

डिस्कवरी इनपुट्स (क्लाइंट्स Gateway का पता कैसे सीखते हैं)¶

1. Bonjour / mDNS (केवल LAN)¶

Bonjour best-effort है और नेटवर्क्स के पार काम नहीं करता। यह केवल “same LAN” सुविधा के लिए उपयोग होता है।

लक्ष्य दिशा:

• Gateway Bonjour के माध्यम से अपने WS एंडपॉइंट का विज्ञापन करता है।
• क्लाइंट्स ब्राउज़ करते हैं और “Gateway चुनें” सूची दिखाते हैं, फिर चुने गए एंडपॉइंट को सहेजते हैं।

समस्या-निवारण और बीकन विवरण: Bonjour।

सर्विस बीकन विवरण¶

• सर्विस प्रकार:
• _openclaw-gw._tcp (Gateway ट्रांसपोर्ट बीकन)
• TXT कुंजियाँ (गैर-गोपनीय):
• role=gateway
• lanHost=<hostname>.local
• sshPort=22 (या जो भी विज्ञापित हो)
• gatewayPort=18789 (Gateway WS + HTTP)
• gatewayTls=1 (केवल जब TLS सक्षम हो)
• gatewayTlsSha256=<sha256> (केवल जब TLS सक्षम हो और फ़िंगरप्रिंट उपलब्ध हो)
• canvasPort=18793 (डिफ़ॉल्ट कैनवस होस्ट पोर्ट; /__openclaw__/canvas/ परोसता है)
• cliPath=<path> (वैकल्पिक; चलाने योग्य openclaw एंट्रीपॉइंट या बाइनरी का एब्सोल्यूट पाथ)
• tailnetDns=<magicdns> (वैकल्पिक संकेत; Tailscale उपलब्ध होने पर ऑटो-डिटेक्ट)

अक्षम/ओवरराइड:

• OPENCLAW_DISABLE_BONJOUR=1 विज्ञापन को अक्षम करता है।
• gateway.bind ~/.openclaw/openclaw.json में Gateway बाइंड मोड नियंत्रित करता है।
• OPENCLAW_SSH_PORT TXT में विज्ञापित SSH पोर्ट को ओवरराइड करता है (डिफ़ॉल्ट 22)।
• OPENCLAW_TAILNET_DNS एक tailnetDns संकेत प्रकाशित करता है (MagicDNS)।
• OPENCLAW_CLI_PATH विज्ञापित CLI पाथ को ओवरराइड करता है।

2. Tailnet (क्रॉस-नेटवर्क)¶

London/Vienna जैसे सेटअप्स के लिए, Bonjour मदद नहीं करेगा। अनुशंसित “direct” टार्गेट है:

• Tailscale MagicDNS नाम (प्राथमिक) या एक स्थिर tailnet IP।

यदि Gateway यह पता लगा सकता है कि वह Tailscale के अंतर्गत चल रहा है, तो वह क्लाइंट्स के लिए (वाइड-एरिया बीकन्स सहित) tailnetDns को वैकल्पिक संकेत के रूप में प्रकाशित करता है।

3. मैनुअल / SSH लक्ष्य¶

जब कोई direct रूट न हो (या direct अक्षम हो), तो क्लाइंट्स हमेशा loopback Gateway पोर्ट को फ़ॉरवर्ड करके SSH के माध्यम से कनेक्ट कर सकते हैं।

देखें Remote access।

ट्रांसपोर्ट चयन (क्लाइंट नीति)¶

अनुशंसित क्लाइंट व्यवहार:

1. यदि कोई पेयर्ड direct एंडपॉइंट कॉन्फ़िगर और पहुँच योग्य है, तो उसका उपयोग करें।
2. अन्यथा, यदि Bonjour LAN पर Gateway ढूँढ ले, तो एक-टैप “इस Gateway का उपयोग करें” विकल्प दें और इसे direct एंडपॉइंट के रूप में सहेजें।
3. अन्यथा, यदि tailnet DNS/IP कॉन्फ़िगर है, तो direct प्रयास करें।
4. अन्यथा, SSH पर फ़ॉलबैक करें।

पेयरिंग + प्रमाणीकरण (direct ट्रांसपोर्ट)¶

Gateway नोड/क्लाइंट प्रवेश के लिए सत्य का स्रोत है।

• पेयरिंग अनुरोध Gateway में बनाए/स्वीकृत/अस्वीकृत किए जाते हैं (देखें Gateway pairing)।
• Gateway निम्नलिखित को लागू करता है:
• प्रमाणीकरण (टोकन / की-पेयर)
• scopes/ACLs (Gateway हर विधि के लिए कच्चा प्रॉक्सी नहीं है)
• रेट लिमिट्स

घटक अनुसार ज़िम्मेदारियाँ¶

• Gateway: डिस्कवरी बीकन्स का विज्ञापन करता है, पेयरिंग निर्णयों का स्वामी है, और WS एंडपॉइंट होस्ट करता है।
• macOS ऐप: Gateway चुनने में मदद करता है, पेयरिंग प्रॉम्प्ट्स दिखाता है, और केवल फ़ॉलबैक के रूप में SSH का उपयोग करता है।
• iOS/Android नोड्स: सुविधा के लिए Bonjour ब्राउज़ करते हैं और पेयर्ड Gateway WS से कनेक्ट करते हैं।