Gateway

• डिफ़ॉल्ट रूप से, Gateway तब तक शुरू होने से इनकार करता है जब तक ~/.openclaw/openclaw.json में gateway.mode=local सेट न हो। ad-hoc/dev runs के लिए --allow-unconfigured का उपयोग करें।
• openclaw onboard --mode local और openclaw setup से gateway.mode=local लिखे जाने की अपेक्षा है। अगर फ़ाइल मौजूद है लेकिन gateway.mode नहीं है, तो इसे implicit रूप से local mode मानने के बजाय टूटी या clobbered config मानकर सुधारें।
• अगर फ़ाइल मौजूद है और gateway.mode नहीं है, तो Gateway इसे संदिग्ध config क्षति मानता है और आपके लिए "guess local" करने से इनकार करता है।
• auth के बिना loopback से आगे bind करना रोका गया है (safety guardrail)।
• lan, tailnet, और custom अभी IPv4-only BYOH paths पर resolve होते हैं।
• IPv6-only BYOH आज इस path पर natively supported नहीं है। अगर host खुद IPv6-only है, तो IPv4 sidecar या proxy का उपयोग करें।
• authorized होने पर SIGUSR1 in-process restart trigger करता है (commands.restart डिफ़ॉल्ट रूप से enabled है; manual restart रोकने के लिए commands.restart: false सेट करें, जबकि gateway tool/config apply/update allowed रहते हैं)।
• SIGINT/SIGTERM handlers gateway process रोकते हैं, लेकिन वे कोई 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, approval ids, 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 set करें।
• 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 होने पर भी gateway status diagnostics के लिए उपलब्ध रहता है।
• डिफ़ॉल्ट gateway status service state, WebSocket connect, और handshake time पर दिखाई देने वाली auth capability साबित करता है। यह read/write/admin operations साबित नहीं करता।
• Diagnostic probes first-time device auth के लिए non-mutating हैं: वे मौजूद होने पर मौजूदा 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 suppress कर दी जाती हैं।
• 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 extra launchd/systemd/schtasks installs के लिए best-effort scan जोड़ता है। जब multiple gateway-like services detect होती हैं, human output cleanup hints print करता है और warn करता है कि अधिकतर setups को प्रति machine एक gateway चलाना चाहिए।
• --deep recent Gateway supervisor restart handoff भी report करता है जब service process external supervisor restart के लिए cleanly exited हो।
• --deep plugin-aware mode (pluginValidation: "full") में config validation चलाता है और configured plugin manifest warnings (उदाहरण के लिए missing channel config metadata) surface करता है ताकि install और update smoke checks उन्हें पकड़ सकें। डिफ़ॉल्ट gateway status fast read-only path रखता है जो plugin validation छोड़ता है।
• 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 नहीं है (explicit gateway.auth.mode of password/none/trusted-proxy, या mode unset जहां password win कर सकता है और कोई token candidate win नहीं कर सकता), तो token-drift checks config token resolution छोड़ देते हैं।

• Reachable: yes का मतलब है कि कम से कम एक target ने WebSocket connect accept किया।
• Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only report करता है कि probe auth के बारे में क्या prove कर सकी। यह 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 है। इसे degraded reachability के रूप में report किया जाता है, full failure के रूप में नहीं।
• Connect: ok के बाद Read probe: failed का मतलब है कि Gateway ने WebSocket connection accept किया, लेकिन follow-up read diagnostics timed out या failed। यह भी degraded reachability है, unreachable Gateway नहीं।
• gateway status की तरह, probe existing cached device auth reuse करता है लेकिन first-time device identity या pairing state create नहीं करता।
• Exit code non-zero केवल तब होता है जब कोई probed target reachable नहीं है।

Top level:

• ok: कम से कम एक target reachable है।
• degraded: कम से कम एक target ने connection accept किया लेकिन full detail RPC diagnostics complete नहीं किए।
• capability: reachable targets में देखी गई best capability (read_only, write_capable, admin_capable, pairing_pending, connected_no_operator_scope, या unknown)।
• primaryTargetId: इस order में 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 यह prove नहीं कर सका कि 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 को बनाए रखे बिना current boot session से LaunchAgent को हटाता है — KeepAlive auto-recovery future crashes के लिए active रहती है और gateway start manual launchctl enable के बिना cleanly re-enable करता है। KeepAlive और RunAtLoad को persistently suppress करने के लिए --disable पास करें, ताकि gateway अगले explicit gateway start तक respawn न हो; इसका उपयोग तब करें जब manual stop को reboots या system restarts के बाद भी बना रहना चाहिए।
• gateway restart --safe running Gateway से active work को preflight करने और active work drain होने के बाद एक coalesced restart schedule करने को कहता है। default safe restart configured gateway.reload.deferralTimeoutMs (default 5 minutes) तक active work की प्रतीक्षा करता है; जब वह budget समाप्त हो जाता है, restart forced होता है। ऐसे indefinite safe wait के लिए जो कभी force नहीं करता, gateway.reload.deferralTimeoutMs को 0 पर सेट करें। --safe को --force या --wait के साथ combine नहीं किया जा सकता।
• gateway restart --wait 30s उस restart के लिए configured restart drain budget को override करता है। bare numbers milliseconds होते हैं; s, m, और h जैसी units स्वीकार की जाती हैं। --wait 0 indefinite प्रतीक्षा करता है।
• 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 है, तो install तब तक blocked रहता है जब तक mode explicit रूप से set न हो।