Gateway प्रोटोकॉल

Gateway WS प्रोटोकॉल OpenClaw के लिए एकमात्र कंट्रोल प्लेन + नोड ट्रांसपोर्ट है। सभी क्लाइंट (CLI, वेब UI, macOS ऐप, iOS/Android नोड, हेडलेस नोड) WebSocket पर कनेक्ट होते हैं और हैंडशेक समय पर अपनी भूमिका + स्कोप घोषित करते हैं।

ट्रांसपोर्ट

• WebSocket, JSON पेलोड वाले टेक्स्ट फ्रेम।
• पहला फ्रेम अनिवार्य रूप से connect अनुरोध होना चाहिए।
• प्री-कनेक्ट फ्रेम 64 KiB तक सीमित हैं। सफल हैंडशेक के बाद, क्लाइंट को hello-ok.policy.maxPayload और hello-ok.policy.maxBufferedBytes सीमाओं का पालन करना चाहिए। डायग्नॉस्टिक्स सक्षम होने पर, बहुत बड़े इनबाउंड फ्रेम और धीमे आउटबाउंड बफर gateway के प्रभावित फ्रेम को बंद करने या छोड़ने से पहले payload.large इवेंट उत्सर्जित करते हैं। ये इवेंट आकार, सीमाएँ, सतहें, और सुरक्षित कारण कोड रखते हैं। वे संदेश बॉडी, अटैचमेंट सामग्री, रॉ फ्रेम बॉडी, टोकन, कुकीज़, या गुप्त मान नहीं रखते।

हैंडशेक (connect)

Gateway → क्लाइंट (प्री-कनेक्ट चुनौती):

{  "type": "event",  "event": "connect.challenge",  "payload": { "nonce": "…", "ts": 1737264000000 }}

क्लाइंट → Gateway:

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "cli",      "version": "1.2.3",      "platform": "macos",      "mode": "operator"    },    "role": "operator",    "scopes": ["operator.read", "operator.write"],    "caps": [],    "commands": [],    "permissions": {},    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-cli/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

Gateway → क्लाइंट:

{  "type": "res",  "id": "…",  "ok": true,  "payload": {    "type": "hello-ok",    "protocol": 4,    "server": { "version": "…", "connId": "…" },    "features": { "methods": ["…"], "events": ["…"] },    "snapshot": { "…": "…" },    "auth": {      "role": "operator",      "scopes": ["operator.read", "operator.write"]    },    "policy": {      "maxPayload": 26214400,      "maxBufferedBytes": 52428800,      "tickIntervalMs": 15000    }  }}

जब Gateway अभी भी स्टार्टअप साइडकार पूरा कर रहा हो, तो connect अनुरोध details.reason को "startup-sidecars" और retryAfterMs पर सेट किए हुए पुनः प्रयास योग्य UNAVAILABLE त्रुटि लौटा सकता है। क्लाइंट को इसे अंतिम हैंडशेक विफलता के रूप में दिखाने के बजाय अपने कुल कनेक्शन बजट के भीतर उस प्रतिक्रिया का पुनः प्रयास करना चाहिए।

server, features, snapshot, और policy सभी स्कीमा (packages/gateway-protocol/src/schema/frames.ts) द्वारा आवश्यक हैं। auth भी आवश्यक है और नेगोशिएट की गई भूमिका/स्कोप रिपोर्ट करता है। pluginSurfaceUrls वैकल्पिक है और canvas जैसे Plugin सतह नामों को स्कोप किए गए होस्टेड URL से मैप करता है।

स्कोप किए गए Plugin सतह URL समाप्त हो सकते हैं। नोड { "surface": "canvas" } के साथ node.pluginSurface.refresh कॉल करके pluginSurfaceUrls में नया एंट्री प्राप्त कर सकते हैं। प्रायोगिक Canvas Plugin रिफैक्टर बहिष्कृत canvasHostUrl, canvasCapability, या node.canvas.capability.refresh संगतता पथ का समर्थन नहीं करता; वर्तमान नेटिव क्लाइंट और gateway को Plugin सतहों का उपयोग करना चाहिए।

जब कोई डिवाइस टोकन जारी नहीं होता, तो hello-ok.auth टोकन फ़ील्ड के बिना नेगोशिएट की गई अनुमतियाँ रिपोर्ट करता है:

{  "auth": {    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

विश्वसनीय समान-प्रक्रिया बैकएंड क्लाइंट (client.id: "gateway-client", client.mode: "backend") साझा gateway टोकन/पासवर्ड से प्रमाणीकरण करने पर सीधे loopback कनेक्शन पर device छोड़ सकते हैं। यह पथ आंतरिक कंट्रोल-प्लेन RPCs के लिए आरक्षित है और पुराने CLI/डिवाइस पेयरिंग बेसलाइन को सबएजेंट सेशन अपडेट जैसे स्थानीय बैकएंड कार्य को ब्लॉक करने से रोकता है। रिमोट क्लाइंट, ब्राउज़र-ओरिजिन क्लाइंट, नोड क्लाइंट, और स्पष्ट डिवाइस-टोकन/डिवाइस-आइडेंटिटी क्लाइंट अभी भी सामान्य पेयरिंग और स्कोप-अपग्रेड जांचों का उपयोग करते हैं।

जब डिवाइस टोकन जारी होता है, तो hello-ok में यह भी शामिल होता है:

{  "auth": {    "deviceToken": "…",    "role": "operator",    "scopes": ["operator.read", "operator.write"]  }}

बिल्ट-इन QR/setup-code बूटस्ट्रैप एक नया मोबाइल हैंडऑफ पथ है। सफल बेसलाइन setup-code connect एक प्राथमिक नोड टोकन और एक सीमित operator टोकन लौटाता है:

{  "auth": {    "deviceToken": "…",    "role": "node",    "scopes": [],    "deviceTokens": [      {        "deviceToken": "…",        "role": "operator",        "scopes": ["operator.approvals", "operator.read", "operator.talk.secrets", "operator.write"]      }    ]  }}

operator हैंडऑफ जानबूझकर सीमित है ताकि QR ऑनबोर्डिंग मोबाइल operator लूप शुरू कर सके और पेयरिंग म्यूटेशन स्कोप या operator.admin दिए बिना नेटिव सेटअप पूरा कर सके। इसमें operator.talk.secrets शामिल है ताकि नेटिव क्लाइंट बूटस्ट्रैप के बाद आवश्यक Talk कॉन्फ़िगरेशन पढ़ सके। व्यापक पेयरिंग और एडमिन एक्सेस के लिए अलग स्वीकृत operator पेयरिंग या टोकन फ़्लो चाहिए। क्लाइंट को hello-ok.auth.deviceTokens केवल तब स्थायी रखना चाहिए जब connect ने wss:// या loopback/local pairing जैसे विश्वसनीय ट्रांसपोर्ट पर बूटस्ट्रैप auth का उपयोग किया हो।

नोड उदाहरण

{  "type": "req",  "id": "…",  "method": "connect",  "params": {    "minProtocol": 3,    "maxProtocol": 4,    "client": {      "id": "ios-node",      "version": "1.2.3",      "platform": "ios",      "mode": "node"    },    "role": "node",    "scopes": [],    "caps": ["camera", "canvas", "screen", "location", "voice"],    "commands": ["camera.snap", "canvas.navigate", "screen.record", "location.get"],    "permissions": { "camera.capture": true, "screen.record": false },    "auth": { "token": "…" },    "locale": "en-US",    "userAgent": "openclaw-ios/1.2.3",    "device": {      "id": "device_fingerprint",      "publicKey": "…",      "signature": "…",      "signedAt": 1737264000000,      "nonce": "…"    }  }}

फ्रेमिंग

• अनुरोध: {type:"req", id, method, params}
• प्रतिक्रिया: {type:"res", id, ok, payload|error}
• इवेंट: {type:"event", event, payload, seq?, stateVersion?}

साइड-इफ़ेक्ट करने वाली विधियों के लिए idempotency keys आवश्यक हैं (स्कीमा देखें)।

भूमिकाएँ + स्कोप

पूर्ण operator स्कोप मॉडल, approval-time जांचों, और shared-secret अर्थों के लिए, Operator scopes देखें।

भूमिकाएँ

• operator = कंट्रोल प्लेन क्लाइंट (CLI/UI/ऑटोमेशन)।
• node = क्षमता होस्ट (camera/screen/canvas/system.run)।

स्कोप (operator)

सामान्य स्कोप:

• operator.read
• operator.write
• operator.admin
• operator.approvals
• operator.pairing
• operator.talk.secrets

includeSecrets: true के साथ talk.config के लिए operator.talk.secrets (या operator.admin) आवश्यक है। जब सीक्रेट शामिल हों, तो क्लाइंट को सक्रिय Talk provider credential talk.resolved.config.apiKey से पढ़ना चाहिए; talk.providers.<id>.apiKey स्रोत-आकार में रहता है और SecretRef ऑब्जेक्ट या संपादित स्ट्रिंग हो सकता है।

Plugin-registered gateway RPC विधियाँ अपना operator स्कोप मांग सकती हैं, लेकिन आरक्षित core admin prefixes (config.*, exec.approvals.*, wizard.*, update.*) हमेशा operator.admin में रिज़ॉल्व होते हैं।

विधि स्कोप केवल पहला गेट है। chat.send के माध्यम से पहुँचे कुछ slash commands इसके ऊपर अधिक कड़ी command-level जांच लागू करते हैं। उदाहरण के लिए, स्थायी /config set और /config unset writes के लिए operator.admin आवश्यक है।

node.pair.approve में base method scope के ऊपर अतिरिक्त approval-time scope check भी है:

• कमांड-रहित अनुरोध: operator.pairing
• non-exec node commands वाले अनुरोध: operator.pairing + operator.write
• ऐसे अनुरोध जिनमें system.run, system.run.prepare, या system.which शामिल हो: operator.pairing + operator.admin

कैप्स/कमांड/अनुमतियाँ (नोड)

नोड connect समय पर capability claims घोषित करते हैं:

• caps: उच्च-स्तरीय capability categories जैसे camera, canvas, screen, location, voice, और talk।
• commands: invoke के लिए command allowlist।
• permissions: सूक्ष्म toggles (जैसे screen.record, camera.capture)।

Gateway इन्हें claims मानता है और server-side allowlists लागू करता है।

उपस्थिति

• system-presence डिवाइस पहचान द्वारा keyed entries लौटाता है।
• उपस्थिति entries में deviceId, roles, और scopes शामिल होते हैं ताकि UI प्रति डिवाइस एक ही row दिखा सकें, भले ही वह operator और node दोनों के रूप में कनेक्ट हो।
• node.list में वैकल्पिक lastSeenAtMs और lastSeenReason फ़ील्ड शामिल हैं। कनेक्टेड नोड अपने वर्तमान कनेक्शन समय को connect कारण के साथ lastSeenAtMs के रूप में रिपोर्ट करते हैं; paired nodes विश्वसनीय नोड इवेंट द्वारा उनकी pairing metadata अपडेट किए जाने पर durable background presence भी रिपोर्ट कर सकते हैं।

नोड बैकग्राउंड alive इवेंट

नोड event: "node.presence.alive" के साथ node.event कॉल कर सकते हैं ताकि रिकॉर्ड हो कि paired node background wake के दौरान connected चिह्नित हुए बिना alive था।

{  "event": "node.presence.alive",  "payloadJSON": "{\"trigger\":\"silent_push\",\"sentAtMs\":1737264000000,\"displayName\":\"Peter's iPhone\",\"version\":\"2026.4.28\",\"platform\":\"iOS 18.4.0\",\"deviceFamily\":\"iPhone\",\"modelIdentifier\":\"iPhone17,1\",\"pushTransport\":\"relay\"}"}

trigger एक बंद enum है: background, silent_push, bg_app_refresh, significant_location, manual, या connect। अज्ञात trigger strings को persistence से पहले gateway द्वारा background में normalized किया जाता है। इवेंट केवल authenticated node device sessions के लिए durable है; device-less या unpaired sessions handled: false लौटाते हैं।

सफल gateway structured result लौटाते हैं:

{  "ok": true,  "event": "node.presence.alive",  "handled": true,  "reason": "persisted"}

पुराने gateway node.event के लिए अभी भी { "ok": true } लौटा सकते हैं; क्लाइंट को इसे acknowledged RPC मानना चाहिए, durable presence persistence नहीं।

ब्रॉडकास्ट इवेंट स्कोपिंग

Server-pushed WebSocket broadcast events scope-gated होते हैं ताकि pairing-scoped या node-only sessions निष्क्रिय रूप से session content प्राप्त न करें।

• Chat, agent, और tool-result frames (streamed agent events और tool call results सहित) के लिए कम से कम operator.read आवश्यक है। operator.read के बिना sessions इन frames को पूरी तरह छोड़ देते हैं।
• Plugin-defined plugin.* broadcasts operator.write या operator.admin तक gated होते हैं, यह इस पर निर्भर करता है कि plugin ने उन्हें कैसे registered किया है।
• Status और transport events (heartbeat, presence, tick, connect/disconnect lifecycle, आदि) unrestricted रहते हैं ताकि transport health हर authenticated session के लिए observable रहे।
• Unknown broadcast event families डिफ़ॉल्ट रूप से scope-gated होते हैं (fail-closed), जब तक कोई registered handler उन्हें स्पष्ट रूप से relax न करे।

हर client connection अपना per-client sequence number रखता है ताकि broadcasts उस socket पर monotonic ordering बनाए रखें, भले ही अलग-अलग clients event stream के अलग-अलग scope-filtered subsets देखें।

सामान्य RPC method families

सार्वजनिक WS surface ऊपर दिए handshake/auth examples से व्यापक है। यह generated dump नहीं है — hello-ok.features.methods src/gateway/server-methods-list.ts और loaded plugin/channel method exports से बनी conservative discovery list है। इसे feature discovery मानें, src/gateway/server-methods/*.ts की full enumeration नहीं।

सामान्य इवेंट परिवार

• chat: UI चैट अपडेट जैसे chat.inject और अन्य केवल-ट्रांसक्रिप्ट चैट इवेंट। प्रोटोकॉल v4 में, डेल्टा पेलोड deltaText रखते हैं; message संचयी असिस्टेंट स्नैपशॉट बना रहता है। गैर-प्रीफ़िक्स प्रतिस्थापन replace=true सेट करते हैं और deltaText को प्रतिस्थापन टेक्स्ट के रूप में उपयोग करते हैं।
• session.message, session.operation, और session.tool: सब्सक्राइब किए गए सेशन के लिए ट्रांसक्रिप्ट, इन-फ़्लाइट सेशन ऑपरेशन, और इवेंट-स्ट्रीम अपडेट।
• sessions.changed: सेशन इंडेक्स या मेटाडेटा बदला।
• presence: सिस्टम प्रेज़ेंस स्नैपशॉट अपडेट।
• tick: आवधिक keepalive / liveness इवेंट।
• health: gateway स्वास्थ्य स्नैपशॉट अपडेट।
• heartbeat: heartbeat इवेंट स्ट्रीम अपडेट।
• cron: cron रन/जॉब परिवर्तन इवेंट।
• shutdown: gateway शटडाउन सूचना।
• node.pair.requested / node.pair.resolved: नोड पेयरिंग जीवनचक्र।
• node.invoke.request: नोड इनवोक अनुरोध प्रसारण।
• device.pair.requested / device.pair.resolved: पेयर्ड-डिवाइस जीवनचक्र।
• voicewake.changed: वेक-वर्ड ट्रिगर कॉन्फ़िग बदला।
• exec.approval.requested / exec.approval.resolved: exec स्वीकृति जीवनचक्र।
• plugin.approval.requested / plugin.approval.resolved: plugin स्वीकृति जीवनचक्र।

नोड हेल्पर विधियाँ

• नोड ऑटो-अलाउ जाँचों के लिए कौशल निष्पाद्य फ़ाइलों की वर्तमान सूची पाने हेतु skills.bins कॉल कर सकते हैं।

टास्क लेजर RPC

ऑपरेटर क्लाइंट टास्क लेजर RPC के माध्यम से Gateway बैकग्राउंड टास्क रिकॉर्ड का निरीक्षण और रद्द कर सकते हैं। ये विधियाँ स्वच्छ किए गए टास्क सारांश लौटाती हैं, कच्ची रनटाइम स्थिति नहीं।

• tasks.list के लिए operator.read आवश्यक है।
  • पैरामीटर: वैकल्पिक status ("queued", "running", "completed", "failed", "cancelled", या "timed_out") या उन स्थितियों की सरणी, वैकल्पिक agentId, वैकल्पिक sessionKey, वैकल्पिक limit 1 से 500 तक, और वैकल्पिक स्ट्रिंग cursor।
  • परिणाम: { "tasks": TaskSummary[], "nextCursor"?: string }।
• tasks.get के लिए operator.read आवश्यक है।
  • पैरामीटर: { "taskId": string }।
  • परिणाम: { "task": TaskSummary }।
  • अनुपस्थित टास्क id Gateway not-found त्रुटि आकार लौटाते हैं।
• tasks.cancel के लिए operator.write आवश्यक है।
  • पैरामीटर: { "taskId": string, "reason"?: string }।
  • परिणाम: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }।
  • found रिपोर्ट करता है कि लेजर में मेल खाता टास्क था या नहीं। cancelled रिपोर्ट करता है कि रनटाइम ने रद्दीकरण स्वीकार किया या रिकॉर्ड किया या नहीं।

TaskSummary में id, status, और वैकल्पिक मेटाडेटा शामिल हैं, जैसे kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, टाइमस्टैम्प, प्रगति, टर्मिनल सारांश, और स्वच्छ किया गया त्रुटि टेक्स्ट। agentId टास्क निष्पादित कर रहे एजेंट की पहचान करता है; sessionKey और ownerKey अनुरोधकर्ता और नियंत्रण संदर्भ को सुरक्षित रखते हैं।

ऑपरेटर हेल्पर विधियाँ

• ऑपरेटर किसी एजेंट के लिए रनटाइम कमांड इन्वेंटरी लाने हेतु commands.list (operator.read) कॉल कर सकते हैं।
  • agentId वैकल्पिक है; डिफ़ॉल्ट एजेंट कार्यस्थान पढ़ने के लिए इसे छोड़ दें।
  • scope नियंत्रित करता है कि प्राथमिक name किस सतह को लक्षित करता है:
    • text अग्रणी / के बिना प्राथमिक टेक्स्ट कमांड टोकन लौटाता है
    • native और डिफ़ॉल्ट both पथ उपलब्ध होने पर प्रदाता-सचेत नेटिव नाम लौटाते हैं
  • textAliases /model और /m जैसे सटीक स्लैश उपनाम रखता है।
  • nativeName प्रदाता-सचेत नेटिव कमांड नाम रखता है, जब कोई मौजूद हो।
  • provider वैकल्पिक है और केवल नेटिव नामकरण तथा नेटिव Plugin कमांड उपलब्धता को प्रभावित करता है।
  • includeArgs=false प्रतिक्रिया से क्रमबद्ध आर्ग्युमेंट मेटाडेटा हटा देता है।
• ऑपरेटर किसी एजेंट के लिए रनटाइम टूल कैटलॉग लाने हेतु tools.catalog (operator.read) कॉल कर सकते हैं। प्रतिक्रिया में समूहबद्ध टूल और उत्पत्ति मेटाडेटा शामिल होते हैं:
  • source: core या plugin
  • pluginId: source="plugin" होने पर Plugin स्वामी
  • optional: क्या कोई Plugin टूल वैकल्पिक है
• ऑपरेटर किसी सत्र के लिए रनटाइम-प्रभावी टूल इन्वेंटरी लाने हेतु tools.effective (operator.read) कॉल कर सकते हैं।
  • sessionKey आवश्यक है।
  • Gateway कॉलर-आपूर्ति किए गए ऑथ या डिलीवरी संदर्भ को स्वीकार करने के बजाय सत्र से सर्वर-साइड विश्वसनीय रनटाइम संदर्भ निकालता है।
  • प्रतिक्रिया सक्रिय इन्वेंटरी का सत्र-स्कोप, सर्वर-व्युत्पन्न प्रोजेक्शन है, जिसमें core, Plugin, चैनल, और पहले से खोजे गए MCP सर्वर टूल शामिल हैं।
  • tools.effective MCP के लिए केवल-पठन है: यह अंतिम टूल नीति के माध्यम से गर्म सत्र MCP कैटलॉग को प्रोजेक्ट कर सकता है, लेकिन यह MCP रनटाइम नहीं बनाता, ट्रांसपोर्ट कनेक्ट नहीं करता, या tools/list जारी नहीं करता। यदि कोई मिलान वाला गर्म कैटलॉग मौजूद नहीं है, तो प्रतिक्रिया में mcp-not-yet-connected, mcp-not-yet-listed, या mcp-stale-catalog जैसी सूचना शामिल हो सकती है।
  • प्रभावी टूल प्रविष्टियां source="core", source="plugin", source="channel", या source="mcp" का उपयोग करती हैं।
• ऑपरेटर /tools/invoke जैसे ही Gateway नीति पथ के माध्यम से एक उपलब्ध टूल लागू करने के लिए tools.invoke (operator.write) कॉल कर सकते हैं।
  • name आवश्यक है। args, sessionKey, agentId, confirm, और idempotencyKey वैकल्पिक हैं।
  • यदि sessionKey और agentId दोनों मौजूद हैं, तो हल किए गए सत्र एजेंट को agentId से मेल खाना चाहिए।
  • cron, gateway, और nodes जैसे केवल-स्वामी core wrappers को स्वामी/एडमिन पहचान (operator.admin) चाहिए, भले ही tools.invoke विधि स्वयं operator.write हो।
  • प्रतिक्रिया ok, toolName, वैकल्पिक output, और टाइप किए गए error फ़ील्ड के साथ SDK-सामना करने वाला एनवेलप है। अनुमोदन या नीति अस्वीकार Gateway टूल नीति पाइपलाइन को बायपास करने के बजाय पेलोड में ok:false लौटाते हैं।
• ऑपरेटर किसी एजेंट के लिए दृश्यमान Skills इन्वेंटरी लाने हेतु skills.status (operator.read) कॉल कर सकते हैं।
  • agentId वैकल्पिक है; डिफ़ॉल्ट एजेंट कार्यस्थान पढ़ने के लिए इसे छोड़ दें।
  • प्रतिक्रिया में कच्चे सीक्रेट मानों को उजागर किए बिना पात्रता, अनुपलब्ध आवश्यकताएं, कॉन्फ़िग जांच, और स्वच्छ किए गए इंस्टॉल विकल्प शामिल होते हैं।
• ऑपरेटर ClawHub खोज मेटाडेटा के लिए skills.search और skills.detail (operator.read) कॉल कर सकते हैं।
• ऑपरेटर किसी निजी स्किल आर्काइव को इंस्टॉल करने से पहले स्टेज करने के लिए skills.upload.begin, skills.upload.chunk, और skills.upload.commit (operator.admin) कॉल कर सकते हैं। यह विश्वसनीय क्लाइंट के लिए अलग एडमिन अपलोड पथ है, सामान्य ClawHub स्किल इंस्टॉल प्रवाह नहीं, और skills.install.allowUploadedArchives सक्षम न होने तक डिफ़ॉल्ट रूप से अक्षम रहता है।
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) उस slug और force मान से बंधा अपलोड बनाता है।
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) सटीक डिकोडेड ऑफ़सेट पर बाइट्स जोड़ता है।
  • skills.upload.commit({ uploadId, sha256? }) अंतिम आकार और SHA-256 सत्यापित करता है। कमिट केवल अपलोड को अंतिम रूप देता है; यह स्किल इंस्टॉल नहीं करता।
  • अपलोड किए गए स्किल आर्काइव zip आर्काइव होते हैं जिनमें SKILL.md रूट होता है। आर्काइव का आंतरिक डायरेक्टरी नाम कभी इंस्टॉल लक्ष्य नहीं चुनता।
• ऑपरेटर तीन मोड में skills.install (operator.admin) कॉल कर सकते हैं:
  • ClawHub मोड: { source: "clawhub", slug, version?, force? } डिफ़ॉल्ट एजेंट कार्यस्थान की skills/ डायरेक्टरी में स्किल फ़ोल्डर इंस्टॉल करता है।
  • अपलोड मोड: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } कमिट किए गए अपलोड को डिफ़ॉल्ट एजेंट कार्यस्थान की skills/<slug> डायरेक्टरी में इंस्टॉल करता है। slug और force मान को मूल skills.upload.begin अनुरोध से मेल खाना चाहिए। यह मोड तब तक अस्वीकृत रहता है जब तक skills.install.allowUploadedArchives सक्षम न हो। यह सेटिंग ClawHub इंस्टॉल को प्रभावित नहीं करती।
  • Gateway इंस्टॉलर मोड: { name, installId, timeoutMs? } Gateway होस्ट पर घोषित metadata.openclaw.install कार्रवाई चलाता है। पुराने क्लाइंट अब भी dangerouslyForceUnsafeInstall भेज सकते हैं; यह फ़ील्ड अप्रचलित है, केवल प्रोटोकॉल संगतता के लिए स्वीकार किया जाता है, और अनदेखा किया जाता है। ऑपरेटर-स्वामित्व वाले इंस्टॉल निर्णयों के लिए security.installPolicy का उपयोग करें।
• ऑपरेटर दो मोड में skills.update (operator.admin) कॉल कर सकते हैं:
  • ClawHub मोड डिफ़ॉल्ट एजेंट कार्यस्थान में एक ट्रैक किए गए slug या सभी ट्रैक किए गए ClawHub इंस्टॉल अपडेट करता है।
  • कॉन्फ़िग मोड skills.entries.<skillKey> मानों जैसे enabled, apiKey, और env को पैच करता है।

models.list दृश्य

models.list एक वैकल्पिक view पैरामीटर स्वीकार करता है:

• छोड़ा गया या "default": वर्तमान रनटाइम व्यवहार। यदि agents.defaults.models कॉन्फ़िगर किया गया है, तो प्रतिक्रिया अनुमत कैटलॉग होती है, जिसमें provider/* प्रविष्टियों के लिए गतिशील रूप से खोजे गए मॉडल शामिल होते हैं। अन्यथा प्रतिक्रिया पूरा Gateway कैटलॉग होती है।
• "configured": पिकर-आकार का व्यवहार। यदि agents.defaults.models कॉन्फ़िगर किया गया है, तो यह फिर भी प्राथमिक रहता है, जिसमें provider/* प्रविष्टियों के लिए प्रदाता-स्कोप खोज शामिल है। allowlist के बिना, प्रतिक्रिया स्पष्ट models.providers.*.models प्रविष्टियों का उपयोग करती है, और केवल तब पूरे कैटलॉग पर लौटती है जब कोई कॉन्फ़िगर की गई मॉडल पंक्तियां मौजूद नहीं होतीं।
• "all": पूरा Gateway कैटलॉग, agents.defaults.models को बायपास करते हुए। इसे निदान और खोज UI के लिए उपयोग करें, सामान्य मॉडल पिकर के लिए नहीं।

Exec अनुमोदन

• जब किसी exec अनुरोध को अनुमोदन चाहिए, तो Gateway exec.approval.requested प्रसारित करता है।
• ऑपरेटर क्लाइंट exec.approval.resolve कॉल करके समाधान करते हैं (operator.approvals स्कोप आवश्यक)।
• host=node के लिए, exec.approval.request में systemRunPlan (कैननिकल argv/cwd/rawCommand/सत्र मेटाडेटा) शामिल होना चाहिए। systemRunPlan रहित अनुरोध अस्वीकृत किए जाते हैं।
• अनुमोदन के बाद, आगे भेजे गए node.invoke system.run कॉल उस कैननिकल systemRunPlan को प्रामाणिक कमांड/cwd/सत्र संदर्भ के रूप में पुनः उपयोग करते हैं।
• यदि कोई कॉलर prepare और अंतिम अनुमोदित system.run forward के बीच command, rawCommand, cwd, agentId, या sessionKey बदलता है, तो Gateway बदले हुए पेलोड पर भरोसा करने के बजाय रन अस्वीकृत करता है।

एजेंट डिलीवरी fallback

• agent अनुरोध आउटबाउंड डिलीवरी मांगने के लिए deliver=true शामिल कर सकते हैं।
• bestEffortDeliver=false सख्त व्यवहार रखता है: अनसुलझे या केवल-आंतरिक डिलीवरी लक्ष्य INVALID_REQUEST लौटाते हैं।
• bestEffortDeliver=true तब सत्र-केवल निष्पादन पर fallback की अनुमति देता है जब कोई बाहरी डिलीवर योग्य रूट हल नहीं किया जा सकता (उदाहरण के लिए आंतरिक/webchat सत्र या अस्पष्ट बहु-चैनल कॉन्फ़िग)।
• अंतिम agent परिणामों में डिलीवरी मांगी जाने पर result.deliveryStatus शामिल हो सकता है, जो openclaw agent --json --deliver के लिए दस्तावेज़ित समान sent, suppressed, partial_failed, और failed स्थितियों का उपयोग करता है।

संस्करणीकरण

• PROTOCOL_VERSION packages/gateway-protocol/src/version.ts में रहता है।
• क्लाइंट minProtocol + maxProtocol भेजते हैं; सर्वर उन रेंज को अस्वीकृत करता है जिनमें उसका वर्तमान प्रोटोकॉल शामिल नहीं होता। वर्तमान क्लाइंट और सर्वर को प्रोटोकॉल v4 चाहिए।
• स्कीमा + मॉडल TypeBox परिभाषाओं से जनरेट किए जाते हैं:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

क्लाइंट कॉन्स्टेंट

src/gateway/client.ts में संदर्भ क्लाइंट ये डिफ़ॉल्ट उपयोग करता है। मान प्रोटोकॉल v4 में स्थिर हैं और तृतीय-पक्ष क्लाइंट के लिए अपेक्षित आधाररेखा हैं।

सर्वर hello-ok में प्रभावी policy.tickIntervalMs, policy.maxPayload, और policy.maxBufferedBytes प्रकाशित करता है; क्लाइंट को pre-handshake डिफ़ॉल्ट के बजाय उन मानों का सम्मान करना चाहिए।

Auth

• Shared-secret Gateway auth कॉन्फ़िगर किए गए auth mode के आधार पर connect.params.auth.token या connect.params.auth.password का उपयोग करता है।
• Tailscale Serve जैसे identity-bearing modes (gateway.auth.allowTailscale: true) या non-loopback gateway.auth.mode: "trusted-proxy" connect auth check को connect.params.auth.* के बजाय request headers से पूरा करते हैं।
• Private-ingress gateway.auth.mode: "none" shared-secret connect auth को पूरी तरह छोड़ देता है; उस mode को public/untrusted ingress पर expose न करें।
• Pairing के बाद, Gateway connection role + scopes तक सीमित एक device token जारी करता है। यह hello-ok.auth.deviceToken में लौटाया जाता है और client को future connects के लिए persist करना चाहिए।
• Clients को किसी भी successful connect के बाद primary hello-ok.auth.deviceToken persist करना चाहिए।
• उस stored device token से reconnect करने पर उस token के लिए stored approved scope set भी reuse होना चाहिए। इससे पहले से granted read/probe/status access preserved रहता है और reconnects को चुपचाप narrower implicit admin-only scope में collapse होने से बचाया जाता है।
• Client-side connect auth assembly (selectConnectAuth in src/gateway/client.ts):
  • auth.password orthogonal है और set होने पर हमेशा forward किया जाता है।
  • auth.token priority order में populate होता है: पहले explicit shared token, फिर explicit deviceToken, फिर stored per-device token (deviceId + role से keyed)।
  • auth.bootstrapToken केवल तब भेजा जाता है जब ऊपर में से किसी ने भी auth.token resolve न किया हो। Shared token या कोई भी resolved device token इसे suppress करता है।
  • One-shot AUTH_TOKEN_MISMATCH retry पर stored device token का auto-promotion केवल trusted endpoints तक gated है — loopback, या pinned tlsFingerprint के साथ wss://। Pinning के बिना public wss:// qualify नहीं करता।
• Built-in setup-code bootstrap primary node hello-ok.auth.deviceToken और trusted mobile handoff के लिए hello-ok.auth.deviceTokens में bounded operator token लौटाता है। Operator token native Talk configuration reads के लिए operator.talk.secrets शामिल करता है, लेकिन pairing mutation scopes और operator.admin को exclude करता है।
• जब non-baseline setup-code bootstrap approval का इंतज़ार कर रहा हो, PAIRING_REQUIRED details में recommendedNextStep: "wait_then_retry", retryable: true, और pauseReconnect: false शामिल होते हैं। Clients को request approve होने या token invalid होने तक उसी bootstrap token से reconnect करते रहना चाहिए।
• hello-ok.auth.deviceTokens को केवल तब persist करें जब connect ने bootstrap auth का उपयोग wss:// या loopback/local pairing जैसे trusted transport पर किया हो।
• यदि कोई client explicit deviceToken या explicit scopes देता है, तो वह caller-requested scope set authoritative रहता है; cached scopes केवल तब reuse होते हैं जब client stored per-device token reuse कर रहा हो।
• Device tokens को device.token.rotate और device.token.revoke के ज़रिए rotate/revoke किया जा सकता है (operator.pairing scope आवश्यक)। Node या अन्य non-operator role को rotate या revoke करने के लिए operator.admin भी आवश्यक है।
• device.token.rotate rotation metadata लौटाता है। यह replacement bearer token केवल same-device calls के लिए echo करता है जो पहले से उस device token से authenticated हों, ताकि token-only clients reconnect करने से पहले अपना replacement persist कर सकें। Shared/admin rotations bearer token echo नहीं करते।
• Token issuance, rotation, और revocation उस device की pairing entry में recorded approved role set तक bounded रहते हैं; token mutation किसी device role को expand या target नहीं कर सकता जिसे pairing approval ने कभी grant नहीं किया।
• Paired-device token sessions के लिए, device management self-scoped होता है जब तक caller के पास operator.admin भी न हो: non-admin callers केवल अपने own device entry के operator token को manage कर सकते हैं। Node और अन्य non-operator token management admin-only है, caller के अपने device के लिए भी।
• device.token.rotate और device.token.revoke target operator token scope set को caller के current session scopes के विरुद्ध भी check करते हैं। Non-admin callers अपने पास पहले से मौजूद scope से broader operator token को rotate या revoke नहीं कर सकते।
• Auth failures में error.details.code और recovery hints शामिल होते हैं:
  • error.details.canRetryWithDeviceToken (boolean)
  • error.details.recommendedNextStep (retry_with_device_token, update_auth_configuration, update_auth_credentials, wait_then_retry, review_auth_configuration)
• AUTH_TOKEN_MISMATCH के लिए client behavior:
  • Trusted clients cached per-device token के साथ एक bounded retry attempt कर सकते हैं।
  • यदि वह retry fail हो, तो clients को automatic reconnect loops रोकने चाहिए और operator action guidance surface करनी चाहिए।
• AUTH_SCOPE_MISMATCH का मतलब है कि device token recognized था लेकिन requested role/scopes cover नहीं करता। Clients को इसे bad token के रूप में present नहीं करना चाहिए; operator से re-pair करने या narrower/broader scope contract approve करने को prompt करें।

Device identity + pairing

• Nodes को keypair fingerprint से derived stable device identity (device.id) शामिल करनी चाहिए।
• Gateways per device + role tokens issue करते हैं।
• नए device IDs के लिए pairing approvals आवश्यक हैं, जब तक local auto-approval enabled न हो।
• Pairing auto-approval direct local loopback connects पर centered है।
• OpenClaw में trusted shared-secret helper flows के लिए एक narrow backend/container-local self-connect path भी है।
• Same-host tailnet या LAN connects को pairing के लिए अभी भी remote माना जाता है और approval आवश्यक होता है।
• WS clients आम तौर पर connect के दौरान device identity शामिल करते हैं (operator + node)। केवल device-less operator exceptions explicit trust paths हैं:
  • localhost-only insecure HTTP compatibility के लिए gateway.controlUi.allowInsecureAuth=true।
  • successful gateway.auth.mode: "trusted-proxy" operator Control UI auth।
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, severe security downgrade)।
  • reserved internal helper path पर direct-loopback gateway-client backend RPCs।
• Device identity omit करने के scope consequences होते हैं। जब device-less operator connection explicit trust path के ज़रिए allowed हो, OpenClaw फिर भी self-declared scopes को empty set पर clear करता है, जब तक उस path में named scope-preservation exception न हो। Scope-gated methods फिर missing scope के साथ fail होते हैं।
• gateway.controlUi.dangerouslyDisableDeviceAuth=true Control UI break-glass scope-preservation path है। यह arbitrary custom backend या CLI-shaped WebSocket clients को scopes grant नहीं करता।
• Reserved direct-loopback gateway-client backend helper path scopes केवल internal local control-plane RPCs के लिए preserve करता है; custom backend IDs को यह exception नहीं मिलता।
• सभी connections को server-provided connect.challenge nonce sign करना होगा।

Device auth migration diagnostics

Legacy clients के लिए जो अभी भी pre-challenge signing behavior का उपयोग करते हैं, connect अब error.details.code के अंतर्गत DEVICE_AUTH_* detail codes और stable error.details.reason लौटाता है।

Common migration failures:

Migration target:

• हमेशा connect.challenge का इंतज़ार करें।
• Server nonce शामिल करने वाले v2 payload को sign करें।
• वही nonce connect.params.device.nonce में भेजें।
• Preferred signature payload v3 है, जो device/client/role/scopes/token/nonce fields के अलावा platform और deviceFamily को bind करता है।
• Legacy v2 signatures compatibility के लिए accepted रहते हैं, लेकिन paired-device metadata pinning reconnect पर command policy को अभी भी control करती है।

TLS + pinning

• WS connections के लिए TLS supported है।
• Clients optionally gateway cert fingerprint pin कर सकते हैं (देखें gateway.tls config plus gateway.remote.tlsFingerprint या CLI --tls-fingerprint)।

Scope

यह protocol full Gateway API expose करता है (status, channels, models, chat, agent, sessions, nodes, approvals, etc.)। Exact surface packages/gateway-protocol/src/schema.ts में TypeBox schemas द्वारा defined है।

संबंधित

• Bridge protocol
• Gateway runbook