Gateway

• डिफ़ॉल्ट रूप से, Gateway तब तक शुरू होने से मना करता है जब तक ~/.openclaw/openclaw.json में gateway.mode=local सेट न हो। अस्थायी/dev runs के लिए --allow-unconfigured का उपयोग करें।
• openclaw onboard --mode local और openclaw setup से gateway.mode=local लिखे जाने की अपेक्षा है। यदि फ़ाइल मौजूद है लेकिन gateway.mode गायब है, तो उसे local mode को अप्रत्यक्ष रूप से मानने के बजाय टूटा या overwrite हुआ config मानकर ठीक करें।
• यदि फ़ाइल मौजूद है और gateway.mode गायब है, तो Gateway इसे संदिग्ध config क्षति मानता है और आपके लिए "guess local" करने से मना करता है।
• auth के बिना loopback से आगे bind करना अवरुद्ध है (सुरक्षा guardrail)।
• lan, tailnet, और custom अभी IPv4-only BYOH paths पर resolve होते हैं।
• IPv6-only BYOH आज इस path पर मूल रूप से समर्थित नहीं है। यदि host स्वयं IPv6-only है, तो IPv4 sidecar या proxy का उपयोग करें।
• अधिकृत होने पर SIGUSR1 in-process restart trigger करता है (commands.restart डिफ़ॉल्ट रूप से सक्षम है; manual restart रोकने के लिए commands.restart: false सेट करें, जबकि gateway tool/config apply/update अनुमत रहते हैं)।
• SIGINT/SIGTERM handlers gateway प्रक्रिया रोकते हैं, लेकिन वे कोई custom terminal state restore नहीं करते। यदि आप CLI को TUI या raw-mode input के साथ wrap करते हैं, तो exit से पहले terminal restore करें।

• Records operational metadata रखते हैं: event names, counts, byte sizes, memory readings, queue/session state, channel/plugin names, और redacted session summaries। वे chat text, webhook bodies, tool outputs, raw request या response bodies, tokens, cookies, secret values, hostnames, या raw session ids नहीं रखते। recorder को पूरी तरह disable करने के लिए diagnostics.enabled: false सेट करें।
• fatal Gateway exits, shutdown timeouts, और restart startup failures पर, जब recorder में events हों तो OpenClaw वही diagnostic snapshot ~/.openclaw/logs/stability/openclaw-stability-*.json में लिखता है। newest bundle को openclaw gateway stability --bundle latest से inspect करें; --limit, --type, और --since-seq bundle output पर भी apply होते हैं।

• local CLI config missing या invalid होने पर भी diagnostics के लिए gateway status उपलब्ध रहता है।
• default gateway status service state, WebSocket connect, और handshake time पर दिखने वाली auth capability सिद्ध करता है। यह read/write/admin operations सिद्ध नहीं करता।
• Diagnostic probes first-time device auth के लिए non-mutating हैं: वे मौजूद होने पर existing cached device token का reuse करते हैं, लेकिन केवल status check करने के लिए नया CLI device identity या read-only device pairing record नहीं बनाते।
• gateway status संभव होने पर probe auth के लिए configured auth SecretRefs resolve करता है।
• यदि इस command path में required auth SecretRef unresolved है, तो probe connectivity/auth विफल होने पर gateway status --json rpc.authWarning report करता है; --token/--password स्पष्ट रूप से pass करें या पहले secret source resolve करें।
• यदि probe सफल होता है, तो false positives से बचने के लिए unresolved auth-ref warnings दबा दी जाती हैं।
• probing enabled होने पर, JSON output में gateway.version शामिल होता है जब running Gateway उसे report करता है; यदि follow-up handshake probe version metadata नहीं दे सकता, तो --require-rpc status.runtimeVersion RPC payload पर fall back कर सकता है।
• scripts और automation में --require-rpc का उपयोग करें जब listening service पर्याप्त न हो और आपको read-scope RPC calls भी healthy चाहिए हों।
• --deep अतिरिक्त launchd/systemd/schtasks installs के लिए best-effort scan जोड़ता है। जब कई gateway-like services detect होती हैं, human output cleanup hints प्रिंट करता है और चेतावनी देता है कि अधिकांश setups में प्रति machine एक gateway चलना चाहिए।
• --deep हालिया Gateway supervisor restart handoff भी report करता है जब service process external supervisor restart के लिए साफ़ रूप से exit हुआ हो।
• --deep plugin-aware mode (pluginValidation: "full") में config validation चलाता है और configured plugin manifest warnings (उदाहरण के लिए missing channel config metadata) surface करता है ताकि install और update smoke checks उन्हें पकड़ सकें। default gateway status fast read-only path रखता है जो plugin validation skip करता है।
• Human output resolved file log path के साथ CLI-vs-service config paths/validity snapshot शामिल करता है ताकि profile या state-dir drift diagnose करने में मदद मिले।

• Linux systemd installs पर, service auth drift checks unit से Environment= और EnvironmentFile= values दोनों पढ़ते हैं (जिसमें %h, quoted paths, multiple files, और optional - files शामिल हैं)।
• Drift checks merged runtime env (पहले service command env, फिर process env fallback) का उपयोग करके gateway.auth.token SecretRefs resolve करते हैं।
• यदि token auth effectively active नहीं है (password/none/trusted-proxy का explicit gateway.auth.mode, या mode unset जहाँ password जीत सकता है और कोई token candidate नहीं जीत सकता), तो token-drift checks config token resolution skip करते हैं।

• Reachable: yes का अर्थ है कि कम से कम एक target ने WebSocket connect स्वीकार किया।
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only report करता है कि probe auth के बारे में क्या सिद्ध कर सका। यह reachability से अलग है।
• Read probe: ok का अर्थ है कि read-scope detail RPC calls (health/status/system-presence/config.get) भी सफल हुईं।
• Read probe: limited - missing scope: operator.read का अर्थ है connect सफल हुआ लेकिन read-scope RPC limited है। इसे full failure नहीं, बल्कि degraded reachability के रूप में report किया जाता है।
• Read probe: failed after Connect: ok का अर्थ है Gateway ने WebSocket connection स्वीकार किया, लेकिन follow-up read diagnostics timed out या failed हुए। यह भी unreachable Gateway नहीं, बल्कि degraded reachability है।
• gateway status की तरह, probe existing cached device auth का reuse करता है लेकिन first-time device identity या pairing state नहीं बनाता।
• Exit code केवल तब non-zero होता है जब कोई भी probed target reachable न हो।

Top level:

• ok: कम से कम एक target reachable है।
• degraded: कम से कम एक target ने connection स्वीकार किया लेकिन full detail RPC diagnostics complete नहीं किए।
• capability: reachable targets में देखी गई best capability (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, या unknown)।
• primaryTargetId: active winner मानने के लिए best target, इस क्रम में: explicit URL, SSH tunnel, configured remote, फिर local loopback।
• warnings[]: code, message, और optional targetIds वाले best-effort warning records।
• network: current config और host networking से निकले local loopback/tailnet URL hints।
• discovery.timeoutMs और discovery.count: इस probe pass के लिए उपयोग किए गए actual discovery budget/result count।

Per target (targets[].connect):

• ok: connect + degraded classification के बाद reachability।
• rpcOk: full detail RPC success।
• scopeLimited: missing operator scope के कारण detail RPC failed।

Per target (targets[].auth):

• role: उपलब्ध होने पर hello-ok में report की गई auth role।
• scopes: उपलब्ध होने पर hello-ok में report किए गए granted scopes।
• capability: उस target के लिए surfaced auth capability classification।

• ssh_tunnel_failed: SSH tunnel setup failed; command direct probes पर fall back हुआ।
• multiple_gateways: distinct gateway identities reachable थीं, या OpenClaw यह सिद्ध नहीं कर सका कि reachable targets वही gateway हैं। उसी gateway के लिए SSH tunnel, proxy URL, या configured remote URL यह warning trigger नहीं करते।
• auth_secretref_unresolved: failed target के लिए configured auth SecretRef resolve नहीं हो सका।
• probe_scope_limited: WebSocket connect सफल हुआ, लेकिन read probe missing operator.read से limited था।

• gateway status: --url, --token, --password, --timeout, --no-probe, --require-rpc, --deep, --json
• gateway install: --port, --runtime <node|bun>, --token, --wrapper <path>, --force, --json
• gateway restart: --safe, --skip-deferral, --force, --wait <duration>, --json
• gateway uninstall|start: --json
• gateway stop: --disable, --json

• managed service को restart करने के लिए gateway restart का उपयोग करें। restart substitute के रूप में gateway stop और gateway start को chain न करें।
• macOS पर, gateway stop default रूप से launchctl bootout का उपयोग करता है, जो disable को स्थायी किए बिना वर्तमान boot session से LaunchAgent को हटा देता है — KeepAlive auto-recovery भविष्य के crashes के लिए active रहती है और gateway start manual launchctl enable के बिना साफ़ तौर पर re-enable करता है। KeepAlive और RunAtLoad को लगातार suppress करने के लिए --disable पास करें, ताकि gateway अगले explicit gateway start तक respawn न हो; इसका उपयोग तब करें जब manual stop को reboots या system restarts के बाद भी बने रहना चाहिए।
• gateway restart --safe running Gateway से active OpenClaw work का preflight करने और reply delivery, embedded runs, और task runs drain होने तक restart को defer करने के लिए कहता है। --safe को --force या --wait के साथ combine नहीं किया जा सकता।
• gateway restart --wait 30s उस restart के लिए configured restart drain budget को override करता है। bare numbers milliseconds होते हैं; s, m, और h जैसी units स्वीकार की जाती हैं। --wait 0 अनिश्चित काल तक wait करता है।
• gateway restart --safe --skip-deferral OpenClaw-aware safe restart चलाता है, लेकिन deferral gate को bypass करता है ताकि blockers report होने पर भी Gateway तुरंत restart emit करे। stuck-task-run deferrals के लिए operator escape hatch; --safe आवश्यक है।
• gateway restart --force active-work drain को skip करता है और तुरंत restart करता है। इसका उपयोग तब करें जब operator listed task blockers का पहले ही inspection कर चुका हो और gateway को अभी वापस चाहता हो।
• Lifecycle commands scripting के लिए --json स्वीकार करते हैं।

• जब token auth को token चाहिए और gateway.auth.token SecretRef-managed है, तो gateway install सत्यापित करता है कि SecretRef resolvable है, लेकिन resolved token को service environment metadata में persist नहीं करता।
• यदि token auth को token चाहिए और configured token SecretRef unresolved है, तो install fallback plaintext persist करने के बजाय fail closed होता है।
• gateway run पर password auth के लिए, inline --password के बजाय OPENCLAW_GATEWAY_PASSWORD, --password-file, या SecretRef-backed gateway.auth.password को प्राथमिकता दें।
• inferred auth mode में, shell-only OPENCLAW_GATEWAY_PASSWORD install token requirements को relax नहीं करता; managed service install करते समय durable config (gateway.auth.password या config env) का उपयोग करें।
• यदि gateway.auth.token और gateway.auth.password दोनों configured हैं और gateway.auth.mode unset है, तो mode स्पष्ट रूप से set होने तक install blocked रहता है।