मुख्य सामग्री पर जाएं
दिन-1 स्टार्टअप और दिन-2 संचालन के लिए Gateway सेवा के लिए इस पृष्ठ का उपयोग करें।

गहन समस्या-निवारण

सटीक कमांड लैडर और लॉग सिग्नेचर के साथ लक्षण-प्रथम निदान।

कॉन्फ़िगरेशन

कार्य-उन्मुख सेटअप गाइड + पूर्ण कॉन्फ़िगरेशन संदर्भ।

सीक्रेट्स प्रबंधन

SecretRef अनुबंध, रनटाइम स्नैपशॉट व्यवहार, और माइग्रेट/रीलोड संचालन।

सीक्रेट्स प्लान अनुबंध

सटीक secrets apply लक्ष्य/पथ नियम और केवल-ref auth-profile व्यवहार।

​
5-मिनट का स्थानीय स्टार्टअप

1

Gateway शुरू करें

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

सेवा स्वास्थ्य सत्यापित करें

openclaw gateway status
openclaw status
openclaw logs --follow
स्वस्थ बेसलाइन: Runtime: running, Connectivity probe: ok, और Capability: ... जो आपकी अपेक्षा से मेल खाता हो। जब आपको केवल पहुंच-योग्यता नहीं, बल्कि read-scope RPC प्रमाण चाहिए, तो openclaw gateway status --require-rpc का उपयोग करें।
3

चैनल तैयारी सत्यापित करें

openclaw channels status --probe
पहुंच योग्य gateway के साथ यह प्रति-खाता चैनल जांच और वैकल्पिक ऑडिट लाइव चलाता है। यदि gateway पहुंच योग्य नहीं है, तो CLI लाइव जांच आउटपुट के बजाय केवल-कॉन्फ़िग चैनल सारांश पर वापस चला जाता है।
Gateway कॉन्फ़िग रीलोड सक्रिय कॉन्फ़िग फ़ाइल पथ को देखता है (profile/state डिफ़ॉल्ट से resolve किया गया, या सेट होने पर OPENCLAW_CONFIG_PATH से)। डिफ़ॉल्ट मोड gateway.reload.mode="hybrid" है। पहले सफल लोड के बाद, चल रही प्रक्रिया सक्रिय इन-मेमोरी कॉन्फ़िग स्नैपशॉट परोसती है; सफल रीलोड उस स्नैपशॉट को atomic रूप से बदल देता है।

​
रनटाइम मॉडल

  • रूटिंग, control plane, और चैनल कनेक्शन के लिए एक हमेशा-ऑन प्रक्रिया।
  • इसके लिए एकल multiplexed पोर्ट:
    • WebSocket control/RPC
    • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Plugin HTTP रूट, जैसे वैकल्पिक /api/v1/admin/rpc
    • Control UI और hooks
  • डिफ़ॉल्ट bind मोड: loopback।
  • Auth डिफ़ॉल्ट रूप से आवश्यक है। Shared-secret सेटअप gateway.auth.token / gateway.auth.password (या OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) का उपयोग करते हैं, और non-loopback reverse-proxy सेटअप gateway.auth.mode: "trusted-proxy" का उपयोग कर सकते हैं।

​
OpenAI-compatible endpoints

OpenClaw की सबसे उच्च-प्रभाव वाली compatibility surface अब है:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
यह सेट क्यों महत्वपूर्ण है:
  • अधिकांश Open WebUI, LobeChat, और LibreChat इंटीग्रेशन पहले /v1/models जांचते हैं।
  • कई RAG और memory pipelines /v1/embeddings की अपेक्षा करते हैं।
  • Agent-native clients तेजी से /v1/responses को प्राथमिकता देते हैं।
योजना नोट:
  • /v1/models agent-first है: यह openclaw, openclaw/default, और openclaw/<agentId> लौटाता है।
  • openclaw/default स्थिर alias है जो हमेशा configured default agent पर map होता है।
  • जब आप backend provider/model override चाहते हैं, तो x-openclaw-model का उपयोग करें; अन्यथा चयनित agent का सामान्य model और embedding setup नियंत्रण में रहता है।
ये सभी मुख्य Gateway पोर्ट पर चलते हैं और Gateway HTTP API के बाकी हिस्से जैसी ही trusted operator auth boundary का उपयोग करते हैं। Admin HTTP RPC (POST /api/v1/admin/rpc) host tooling के लिए एक अलग, default-off Plugin रूट है जो WebSocket RPC का उपयोग नहीं कर सकता। Admin HTTP RPC देखें।

​
पोर्ट और bind प्राथमिकता

सेटिंगResolution order
Gateway पोर्ट--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Bind मोडCLI/override → gateway.bind → loopback
इंस्टॉल की गई gateway सेवाएं resolved --port को supervisor metadata में रिकॉर्ड करती हैं। gateway.port बदलने के बाद, openclaw doctor --fix या openclaw gateway install --force चलाएं ताकि launchd/systemd/schtasks प्रक्रिया को नए पोर्ट पर शुरू करें। Gateway startup non-loopback binds के लिए स्थानीय Control UI origins seed करते समय उसी effective port और bind का उपयोग करता है। उदाहरण के लिए, --bind lan --port 3000 runtime validation चलने से पहले http://localhost:3000 और http://127.0.0.1:3000 seed करता है। किसी भी remote browser origins, जैसे HTTPS proxy URLs, को gateway.controlUi.allowedOrigins में स्पष्ट रूप से जोड़ें।

​
Hot reload modes

gateway.reload.modeव्यवहार
offकोई config reload नहीं
hotकेवल hot-safe बदलाव लागू करें
restartreload-required बदलावों पर restart करें
hybrid (default)सुरक्षित होने पर hot-apply करें, आवश्यक होने पर restart करें

​
Operator command set

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep अतिरिक्त service discovery (LaunchDaemons/systemd system units/schtasks) के लिए है, न कि गहरी RPC health probe के लिए।

​
Multiple gateways (same host)

अधिकांश इंस्टॉल में प्रति मशीन एक gateway चलना चाहिए। एक single gateway कई agents और channels host कर सकता है। आपको multiple gateways केवल तब चाहिए जब आप जानबूझकर isolation या rescue bot चाहते हों। उपयोगी जांचें: 
openclaw gateway status --deep
openclaw gateway probe
क्या अपेक्षा करें:
  • gateway status --deep Other gateway-like services detected (best effort) रिपोर्ट कर सकता है और stale launchd/systemd/schtasks installs अभी भी मौजूद होने पर cleanup hints print कर सकता है।
  • gateway probe distinct gateways के जवाब देने पर, या जब OpenClaw यह prove नहीं कर सकता कि reachable targets वही gateway हैं, multiple reachable gateway identities के बारे में warn कर सकता है। उसी gateway के लिए SSH tunnel, proxy URL, या configured remote URL multiple transports वाला एक gateway है, भले ही transport ports अलग हों।
  • यदि यह जानबूझकर है, तो प्रति gateway ports, config/state, और workspace roots isolate करें।
प्रति instance checklist:
  • Unique gateway.port
  • Unique OPENCLAW_CONFIG_PATH
  • Unique OPENCLAW_STATE_DIR
  • Unique agents.defaults.workspace
उदाहरण: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
विस्तृत सेटअप: /gateway/multiple-gateways.

​
Remote access

प्राथमिकता: Tailscale/VPN। Fallback: SSH tunnel। 
ssh -N -L 18789:127.0.0.1:18789 user@host
फिर clients को स्थानीय रूप से ws://127.0.0.1:18789 से connect करें।
SSH tunnels gateway auth को bypass नहीं करते। shared-secret auth के लिए, clients को tunnel पर भी token/password भेजना होगा। identity-bearing modes के लिए, request को फिर भी उस auth path को satisfy करना होगा।
देखें: Remote Gateway, Authentication, Tailscale.

​
Supervision and service lifecycle

production-like reliability के लिए supervised runs का उपयोग करें। 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
restarts के लिए openclaw gateway restart का उपयोग करें। restart substitute के रूप में openclaw gateway stop और openclaw gateway start को chain न करें।macOS पर, gateway stop डिफ़ॉल्ट रूप से launchctl bootout का उपयोग करता है — यह disable persist किए बिना current boot session से LaunchAgent को remove करता है, इसलिए unexpected crashes के बाद भी KeepAlive auto-recovery काम करती है और gateway start cleanly re-enable करता है। reboots के पार auto-respawn को persistently suppress करने के लिए, --disable pass करें: openclaw gateway stop --disable।LaunchAgent labels ai.openclaw.gateway (default) या ai.openclaw.<profile> (named profile) हैं। openclaw doctor service config drift का audit और repair करता है।

​
Dev profile quick path

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
डिफ़ॉल्ट में isolated state/config और base gateway port 19001 शामिल हैं।

​
Protocol quick reference (operator view)

  • पहला client frame connect होना चाहिए।
  • Gateway hello-ok snapshot (presence, health, stateVersion, uptimeMs, limits/policy) लौटाता है।
  • hello-ok.features.methods / events conservative discovery list हैं, हर callable helper route का generated dump नहीं।
  • Requests: req(method, params) → res(ok/payload|error)।
  • सामान्य events में connect.challenge, agent, chat, session.message, session.operation, session.tool, sessions.changed, presence, tick, health, heartbeat, pairing/approval lifecycle events, और shutdown शामिल हैं।
Agent runs दो-stage हैं:
  1. Immediate accepted ack (status:"accepted")
  2. Final completion response (status:"ok"|"error"), बीच में streamed agent events के साथ।
पूर्ण protocol docs देखें: Gateway Protocol.

​
Operational checks

​
Liveness

  • WS खोलें और connect भेजें।
  • snapshot के साथ hello-ok response की अपेक्षा करें।

​
Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Gap recovery

Events replay नहीं किए जाते। sequence gaps पर, जारी रखने से पहले state (health, system-presence) refresh करें।

​
Common failure signatures

हस्ताक्षरसंभावित समस्या
refusing to bind gateway ... without authमान्य Gateway प्रमाणीकरण पथ के बिना गैर-loopback बाइंड
another gateway instance is already listening / EADDRINUSEपोर्ट टकराव
Gateway start blocked: set gateway.mode=localकॉन्फिग रिमोट मोड पर सेट है, या क्षतिग्रस्त कॉन्फिग से local-mode स्टैम्प गायब है
unauthorized during connectक्लाइंट और Gateway के बीच प्रमाणीकरण बेमेल
पूरी निदान सीढ़ियों के लिए, Gateway समस्या निवारण का उपयोग करें।

​
सुरक्षा गारंटियां

  • Gateway प्रोटोकॉल क्लाइंट Gateway अनुपलब्ध होने पर तुरंत विफल होते हैं (कोई अंतर्निहित डायरेक्ट-चैनल फॉलबैक नहीं)।
  • अमान्य/नॉन-कनेक्ट पहले फ्रेम अस्वीकार करके बंद कर दिए जाते हैं।
  • व्यवस्थित शटडाउन सॉकेट बंद होने से पहले shutdown इवेंट उत्सर्जित करता है।
संबंधित:

​
संबंधित