Gateway प्रोटोकॉल

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

ट्रांसपोर्ट

• 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 पर सेट करके retryable UNAVAILABLE त्रुटि लौटा सकता है। क्लाइंट को इसे टर्मिनल हैंडशेक विफलता के रूप में दिखाने के बजाय अपने कुल कनेक्शन बजट के भीतर उस प्रतिक्रिया को फिर से आजमाना चाहिए।

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

Scoped Plugin सतह URL समाप्त हो सकते हैं। Nodes pluginSurfaceUrls में ताजा प्रविष्टि पाने के लिए node.pluginSurface.refresh को { "surface": "canvas" } के साथ कॉल कर सकते हैं। प्रयोगात्मक Canvas Plugin refactor deprecated canvasHostUrl, canvasCapability, या node.canvas.capability.refresh compatibility path का समर्थन नहीं करता; वर्तमान native clients और gateways को Plugin सतहों का उपयोग करना चाहिए।

जब कोई डिवाइस टोकन जारी नहीं किया जाता, तो hello-ok.auth negotiated permissions को token fields के बिना रिपोर्ट करता है:

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

विश्वसनीय same-process backend clients (client.id: "gateway-client", client.mode: "backend") direct loopback connections पर device छोड़ सकते हैं जब वे shared gateway token/password से authenticate करते हैं। यह path internal control-plane RPCs के लिए आरक्षित है और stale CLI/device pairing baselines को subagent session updates जैसे local backend work को block करने से रोकता है। Remote clients, browser-origin clients, node clients, और explicit device-token/device-identity clients अभी भी normal pairing और scope-upgrade checks का उपयोग करते हैं।

जब device token जारी किया जाता है, तो hello-ok में यह भी शामिल होता है:

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

Built-in QR/setup-code bootstrap एक नया mobile handoff path है। सफल baseline setup-code connect primary node token और एक bounded operator token लौटाता है:

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

operator handoff जानबूझकर bounded है ताकि QR onboarding operator.admin या operator.pairing दिए बिना mobile operator loop शुरू कर सके। इसमें operator.talk.secrets शामिल है ताकि native client bootstrap के बाद आवश्यक Talk configuration पढ़ सके। व्यापक admin और pairing scopes के लिए अलग approved operator pairing या token flow आवश्यक है। क्लाइंट को hello-ok.auth.deviceTokens केवल तब persist करना चाहिए जब connect ने wss:// या loopback/local pairing जैसे trusted transport पर bootstrap auth का उपयोग किया हो।

Node उदाहरण

{  "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": "…"    }  }}

फ्रेमिंग

• Request: {type:"req", id, method, params}
• Response: {type:"res", id, ok, payload|error}
• Event: {type:"event", event, payload, seq?, stateVersion?}

Side-effecting methods के लिए idempotency keys आवश्यक हैं (स्कीमा देखें)।

Roles + scopes

पूरे operator scope model, approval-time checks, और shared-secret semantics के लिए, Operator scopes देखें।

Roles

• operator = control plane client (CLI/UI/automation)।
• node = capability host (camera/screen/canvas/system.run)।

Scopes (operator)

सामान्य scopes:

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

includeSecrets: true वाला talk.config operator.talk.secrets (या operator.admin) मांगता है।

Plugin-registered gateway RPC methods अपने operator scope का अनुरोध कर सकते हैं, लेकिन reserved core admin prefixes (config.*, exec.approvals.*, wizard.*, update.*) हमेशा operator.admin पर resolve होते हैं।

Method scope केवल पहला gate है। chat.send के माध्यम से पहुंचे कुछ slash commands इसके ऊपर stricter command-level checks लागू करते हैं। उदाहरण के लिए, persistent /config set और /config unset writes के लिए operator.admin आवश्यक है।

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

• commandless requests: operator.pairing
• non-exec node commands वाले requests: operator.pairing + operator.write
• वे requests जिनमें system.run, system.run.prepare, या system.which शामिल हैं: operator.pairing + operator.admin

Caps/commands/permissions (node)

Nodes connect time पर capability claims घोषित करते हैं:

• caps: camera, canvas, screen, location, voice, और talk जैसी high-level capability categories।
• commands: invoke के लिए command allowlist।
• permissions: granular toggles (जैसे screen.record, camera.capture)।

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

Presence

• system-presence device identity से keyed entries लौटाता है।
• Presence entries में deviceId, roles, और scopes शामिल होते हैं ताकि UIs प्रति device एक ही row दिखा सकें भले ही वह operator और node दोनों के रूप में connect हो।
• node.list में वैकल्पिक lastSeenAtMs और lastSeenReason fields शामिल हैं। Connected nodes अपना current connection time lastSeenAtMs के रूप में reason connect के साथ report करते हैं; paired nodes तब durable background presence भी report कर सकते हैं जब trusted node event उनकी pairing metadata update करता है।

Node background alive event

Nodes event: "node.presence.alive" के साथ node.event कॉल कर सकते हैं ताकि record हो सके कि paired node background wake के दौरान alive था, बिना उसे connected mark किए।

{  "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 एक closed enum है: background, silent_push, bg_app_refresh, significant_location, manual, या connect। Unknown trigger strings को persistence से पहले gateway द्वारा background में normalize किया जाता है। यह event केवल authenticated node device sessions के लिए durable है; device-less या unpaired sessions handled: false लौटाते हैं।

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

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

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

Broadcast event scoping

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 को पूरी तरह skip करते हैं।
• Plugin-defined plugin.* broadcasts Plugin ने उन्हें कैसे register किया है, इसके आधार पर operator.write या operator.admin तक gated होते हैं।
• Status और transport events (heartbeat, presence, tick, connect/disconnect lifecycle, आदि) unrestricted रहते हैं ताकि transport health हर authenticated session को observable रहे।
• Unknown broadcast event families default रूप से scope-gated (fail-closed) होते हैं जब तक कोई registered handler उन्हें explicitly relax न करे।

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

सामान्य RPC method families

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

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

• chat: UI चैट अपडेट जैसे chat.inject और अन्य केवल-ट्रांसक्रिप्ट चैट इवेंट। protocol v4 में, delta payloads deltaText ले जाते हैं; message cumulative assistant snapshot बना रहता है। Non-prefix replacements replace=true सेट करते हैं और deltaText को replacement text के रूप में उपयोग करते हैं।
• session.message, session.operation, और session.tool: subscribed session के लिए transcript, in-flight session operation, और event-stream updates।
• sessions.changed: सत्र इंडेक्स या मेटाडेटा बदला।
• presence: सिस्टम उपस्थिति snapshot updates।
• tick: periodic keepalive / liveness event।
• health: gateway health snapshot update।
• heartbeat: heartbeat event stream update।
• cron: cron run/job change event।
• shutdown: gateway shutdown notification।
• node.pair.requested / node.pair.resolved: नोड पेयरिंग lifecycle।
• node.invoke.request: node invoke request broadcast।
• device.pair.requested / device.pair.resolved: paired-device lifecycle।
• voicewake.changed: wake-word trigger config changed।
• exec.approval.requested / exec.approval.resolved: exec approval lifecycle।
• plugin.approval.requested / plugin.approval.resolved: plugin approval lifecycle।

नोड सहायक विधियां

• नोड auto-allow checks के लिए skill executables की वर्तमान सूची फ़ेच करने हेतु skills.bins कॉल कर सकते हैं।

टास्क लेजर RPCs

ऑपरेटर क्लाइंट task ledger RPCs के माध्यम से Gateway background task records का निरीक्षण और रद्द कर सकते हैं। ये विधियां raw runtime state नहीं, बल्कि sanitized task summaries लौटाती हैं।

• tasks.list के लिए operator.read आवश्यक है।
  • Params: वैकल्पिक status ("queued", "running", "completed", "failed", "cancelled", या "timed_out") या उन statuses की array, वैकल्पिक agentId, वैकल्पिक sessionKey, वैकल्पिक limit 1 से 500 तक, और वैकल्पिक string cursor।
  • Result: { "tasks": TaskSummary[], "nextCursor"?: string }।
• tasks.get के लिए operator.read आवश्यक है।
  • Params: { "taskId": string }।
  • Result: { "task": TaskSummary }।
  • गुम task ids Gateway not-found error shape लौटाते हैं।
• tasks.cancel के लिए operator.write आवश्यक है।
  • Params: { "taskId": string, "reason"?: string }।
  • Result: { "found": boolean, "cancelled": boolean, "reason"?: string, "task"?: TaskSummary }।
  • found रिपोर्ट करता है कि ledger में matching task था या नहीं। cancelled रिपोर्ट करता है कि runtime ने cancellation स्वीकार या record किया या नहीं।

TaskSummary में id, status, और वैकल्पिक मेटाडेटा जैसे kind, runtime, title, agentId, sessionKey, childSessionKey, ownerKey, runId, taskId, flowId, parentTaskId, sourceId, timestamps, progress, terminal summary, और sanitized error text शामिल होते हैं। agentId task execute करने वाले agent की पहचान करता है; sessionKey और ownerKey requester और control context को preserve करते हैं।

ऑपरेटर सहायक विधियां

• ऑपरेटर किसी एजेंट के लिए runtime command inventory प्राप्त करने हेतु commands.list (operator.read) कॉल कर सकते हैं।
  • agentId वैकल्पिक है; default agent workspace पढ़ने के लिए इसे छोड़ दें।
  • scope नियंत्रित करता है कि primary name किस सतह को target करता है:
    • text leading / के बिना primary text command token लौटाता है
    • native और default both path उपलब्ध होने पर provider-aware native names लौटाते हैं
  • textAliases /model और /m जैसे exact slash aliases रखता है।
  • nativeName provider-aware native command name रखता है जब कोई मौजूद हो।
  • provider वैकल्पिक है और केवल native naming तथा native Plugin command availability को प्रभावित करता है।
  • includeArgs=false response से serialized argument metadata हटा देता है।
• ऑपरेटर किसी एजेंट के लिए runtime tool catalog प्राप्त करने हेतु tools.catalog (operator.read) कॉल कर सकते हैं। response में grouped tools और provenance metadata शामिल होते हैं:
  • source: core या plugin
  • pluginId: Plugin owner जब source="plugin"
  • optional: क्या कोई Plugin tool optional है
• ऑपरेटर किसी session के लिए runtime-effective tool inventory प्राप्त करने हेतु tools.effective (operator.read) कॉल कर सकते हैं।
  • sessionKey आवश्यक है।
  • Gateway caller-supplied auth या delivery context स्वीकार करने के बजाय session server-side से trusted runtime context निकालता है।
  • response active inventory का session-scoped server-derived projection है, जिसमें core, Plugin, channel, और पहले से discovered MCP server tools शामिल हैं।
  • tools.effective MCP के लिए read-only है: यह warm session MCP catalog को final tool policy के जरिए project कर सकता है, लेकिन MCP runtimes नहीं बनाता, transports connect नहीं करता, या tools/list issue नहीं करता। यदि कोई matching warm catalog मौजूद नहीं है, तो response में mcp-not-yet-connected, mcp-not-yet-listed, या mcp-stale-catalog जैसा notice शामिल हो सकता है।
  • Effective tool entries source="core", source="plugin", source="channel", या source="mcp" का उपयोग करती हैं।
• ऑपरेटर /tools/invoke जैसे ही Gateway policy path के जरिए एक उपलब्ध tool invoke करने हेतु tools.invoke (operator.write) कॉल कर सकते हैं।
  • name आवश्यक है। args, sessionKey, agentId, confirm, और idempotencyKey वैकल्पिक हैं।
  • यदि sessionKey और agentId दोनों मौजूद हैं, तो resolved session agent को agentId से match करना होगा।
  • cron, gateway, और nodes जैसे owner-only core wrappers को owner/admin identity (operator.admin) चाहिए, भले ही tools.invoke method स्वयं operator.write हो।
  • response SDK-facing envelope है जिसमें ok, toolName, optional output, और typed error fields होते हैं। Approval या policy refusals Gateway tool policy pipeline को bypass करने के बजाय payload में ok:false लौटाते हैं।
• ऑपरेटर किसी एजेंट के लिए visible skill inventory प्राप्त करने हेतु skills.status (operator.read) कॉल कर सकते हैं।
  • agentId वैकल्पिक है; default agent workspace पढ़ने के लिए इसे छोड़ दें।
  • response में eligibility, missing requirements, config checks, और raw secret values उजागर किए बिना sanitized install options शामिल होते हैं।
• ऑपरेटर ClawHub discovery metadata के लिए skills.search और skills.detail (operator.read) कॉल कर सकते हैं।
• ऑपरेटर install करने से पहले private skill archive stage करने हेतु skills.upload.begin, skills.upload.chunk, और skills.upload.commit (operator.admin) कॉल कर सकते हैं। यह trusted clients के लिए अलग admin upload path है, सामान्य ClawHub skill install flow नहीं, और default रूप से disabled रहता है जब तक skills.install.allowUploadedArchives enabled न हो।
  • skills.upload.begin({ kind: "skill-archive", slug, sizeBytes, sha256?, force?, idempotencyKey? }) उस slug और force value से bound upload बनाता है।
  • skills.upload.chunk({ uploadId, offset, dataBase64 }) exact decoded offset पर bytes append करता है।
  • skills.upload.commit({ uploadId, sha256? }) final size और SHA-256 verify करता है। Commit केवल upload को finalize करता है; यह skill install नहीं करता।
  • Uploaded skill archives ऐसे zip archives हैं जिनमें SKILL.md root होता है। archive का internal directory name कभी install target select नहीं करता।
• ऑपरेटर तीन modes में skills.install (operator.admin) कॉल कर सकते हैं:
  • ClawHub mode: { source: "clawhub", slug, version?, force? } default agent workspace skills/ directory में skill folder install करता है।
  • Upload mode: { source: "upload", uploadId, slug, force?, sha256?, timeoutMs? } committed upload को default agent workspace skills/<slug> directory में install करता है। slug और force value को original skills.upload.begin request से match करना होगा। यह mode तब तक rejected रहता है जब तक skills.install.allowUploadedArchives enabled न हो। setting ClawHub installs को प्रभावित नहीं करती।
  • Gateway installer mode: { name, installId, timeoutMs? } Gateway host पर declared metadata.openclaw.install action चलाता है। पुराने clients अभी भी dangerouslyForceUnsafeInstall भेज सकते हैं; यह field deprecated है, केवल protocol compatibility के लिए accepted है, और ignored है। operator-owned install decisions के लिए security.installPolicy का उपयोग करें।
• ऑपरेटर दो modes में skills.update (operator.admin) कॉल कर सकते हैं:
  • ClawHub mode default agent workspace में एक tracked slug या सभी tracked ClawHub installs update करता है।
  • Config mode skills.entries.<skillKey> values जैसे enabled, apiKey, और env patch करता है।

models.list views

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

• Omitted या "default": current runtime behavior. यदि agents.defaults.models configured है, तो response allowed catalog है, जिसमें provider/* entries के लिए dynamically discovered models शामिल हैं। अन्यथा response full Gateway catalog है।
• "configured": picker-sized behavior. यदि agents.defaults.models configured है, तो वही प्राथमिक रहता है, जिसमें provider/* entries के लिए provider-scoped discovery शामिल है। allowlist के बिना, response explicit models.providers.*.models entries का उपयोग करता है, और full catalog पर केवल तभी fallback करता है जब कोई configured model rows मौजूद न हों।
• "all": full Gateway catalog, agents.defaults.models को bypass करते हुए। इसका उपयोग diagnostics और discovery UIs के लिए करें, normal model pickers के लिए नहीं।

Exec approvals

• जब किसी exec request को approval चाहिए, Gateway exec.approval.requested broadcast करता है।
• Operator clients exec.approval.resolve कॉल करके resolve करते हैं (operator.approvals scope आवश्यक है)।
• host=node के लिए, exec.approval.request में systemRunPlan (canonical argv/cwd/rawCommand/session metadata) शामिल होना चाहिए। systemRunPlan missing वाली requests rejected होती हैं।
• approval के बाद, forwarded node.invoke system.run calls उसी canonical systemRunPlan को authoritative command/cwd/session context के रूप में reuse करते हैं।
• यदि कोई caller prepare और final approved system.run forward के बीच command, rawCommand, cwd, agentId, या sessionKey mutate करता है, तो Gateway mutated payload पर trust करने के बजाय run reject करता है।

Agent delivery fallback

• agent requests outbound delivery request करने के लिए deliver=true शामिल कर सकती हैं।
• bestEffortDeliver=false strict behavior रखता है: unresolved या internal-only delivery targets INVALID_REQUEST लौटाते हैं।
• bestEffortDeliver=true तब session-only execution पर fallback की अनुमति देता है जब कोई external deliverable route resolve नहीं हो सकता (उदाहरण के लिए internal/webchat sessions या ambiguous multi-channel configs)।
• Final agent results में delivery requested होने पर result.deliveryStatus शामिल हो सकता है, जो openclaw agent --json --deliver के लिए documented समान sent, suppressed, partial_failed, और failed statuses का उपयोग करता है।

Versioning

• PROTOCOL_VERSION packages/gateway-protocol/src/version.ts में रहता है।
• Clients minProtocol + maxProtocol भेजते हैं; server उन ranges को reject करता है जिनमें उसका current protocol शामिल नहीं है। current clients और servers को protocol v4 चाहिए।
• Schemas + models TypeBox definitions से generated होते हैं:
  • pnpm protocol:gen
  • pnpm protocol:gen:swift
  • pnpm protocol:check

Client constants

src/gateway/client.ts में reference client ये defaults उपयोग करता है। Values protocol v4 में stable हैं और third-party clients के लिए expected baseline हैं।

server effective policy.tickIntervalMs, policy.maxPayload, और policy.maxBufferedBytes को hello-ok में advertise करता है; clients को pre-handshake defaults के बजाय उन values का honor करना चाहिए।

Auth

• Shared-secret Gateway auth कॉन्फ़िगर किए गए auth मोड के आधार पर connect.params.auth.token या connect.params.auth.password का उपयोग करता है।
• Tailscale Serve जैसे पहचान-धारी मोड (gateway.auth.allowTailscale: true) या non-loopback gateway.auth.mode: "trusted-proxy" connect.params.auth.* के बजाय request headers से connect auth जांच पूरी करते हैं।
• Private-ingress gateway.auth.mode: "none" shared-secret connect auth को पूरी तरह छोड़ देता है; इस मोड को public/untrusted ingress पर expose न करें।
• pairing के बाद, Gateway connection role + scopes तक सीमित device token जारी करता है। यह hello-ok.auth.deviceToken में लौटाया जाता है और client को future connects के लिए persist करना चाहिए।
• Clients को किसी भी सफल connect के बाद primary hello-ok.auth.deviceToken persist करना चाहिए।
• उस stored device token के साथ reconnect करने पर उस token के लिए stored approved scope set भी reuse होना चाहिए। यह पहले से granted read/probe/status access को सुरक्षित रखता है और reconnects को चुपचाप संकरे implicit admin-only scope तक घटने से बचाता है।
• Client-side connect auth assembly (src/gateway/client.ts में selectConnectAuth):
  • 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 शामिल है और operator.admin तथा operator.pairing शामिल नहीं हैं।
• जब non-baseline setup-code bootstrap approval की प्रतीक्षा कर रहा हो, PAIRING_REQUIRED details में recommendedNextStep: "wait_then_retry", retryable: true, और pauseReconnect: false शामिल होते हैं। Clients को उसी bootstrap token के साथ reconnect करते रहना चाहिए जब तक request approved न हो जाए या token invalid न हो जाए।
• hello-ok.auth.deviceTokens को केवल तब persist करें जब connect ने trusted transport जैसे wss:// या loopback/local pairing पर bootstrap auth का उपयोग किया हो।
• यदि कोई client explicit deviceToken या explicit scopes supply करता है, तो वह 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 उस approved role set तक bounded रहते हैं जो उस device की pairing entry में recorded है; token mutation pairing approval द्वारा कभी grant न किए गए device role को expand या target नहीं कर सकता।
• Paired-device token sessions के लिए, device management self-scoped होता है जब तक caller के पास operator.admin भी न हो: non-admin callers केवल अपने स्वयं के 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 दिखानी चाहिए।
• AUTH_SCOPE_MISMATCH का अर्थ है कि device token recognized था लेकिन requested role/scopes को cover नहीं करता। Clients को इसे bad token के रूप में present नहीं करना चाहिए; operator को re-pair करने या संकरे/व्यापक scope contract को approve करने के लिए prompt करें।

Device identity + pairing

• Nodes को keypair fingerprint से derived stable device identity (device.id) शामिल करनी चाहिए।
• Gateways प्रति device + role tokens जारी करते हैं।
• नई 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।
  • सफल gateway.auth.mode: "trusted-proxy" operator Control UI auth।
  • gateway.controlUi.dangerouslyDisableDeviceAuth=true (break-glass, गंभीर 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 के अंतर्गत stable error.details.reason के साथ DEVICE_AUTH_* detail codes लौटाता है।

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 वैकल्पिक रूप से gateway cert fingerprint pin कर सकते हैं (gateway.tls config और gateway.remote.tlsFingerprint या CLI --tls-fingerprint देखें)।

Scope

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

Related

• Bridge protocol
• Gateway runbook