Gateway रनबुक

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

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

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

रनटाइम मॉडल

• रूटिंग, 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 प्राथमिकता

इंस्टॉल की गई 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

Operator command set

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw 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 --deepopenclaw 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 19001OPENCLAW_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 करें।

देखें: Remote Gateway, Authentication, Tailscale.

Supervision and service lifecycle

production-like reliability के लिए supervised runs का उपयोग करें।

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

Dev profile quick path

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --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 statusopenclaw channels status --probeopenclaw health

Gap recovery

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

Common failure signatures

पूरी निदान सीढ़ियों के लिए, Gateway समस्या निवारण का उपयोग करें।

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

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

संबंधित:

• समस्या निवारण
• पृष्ठभूमि प्रक्रिया
• कॉन्फिगरेशन
• स्वास्थ्य
• Doctor
• प्रमाणीकरण

संबंधित

• कॉन्फिगरेशन
• Gateway समस्या निवारण
• रिमोट एक्सेस
• सीक्रेट्स प्रबंधन