Gateway संचालन पुस्तिका

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

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

openclaw gateway --port 18789# डीबग/ट्रेस को stdio पर मिरर किया गयाopenclaw gateway --port 18789 --verbose# चयनित पोर्ट पर लिसनर को बलपूर्वक समाप्त करें, फिर शुरू करेंopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

रनटाइम मॉडल

• रूटिंग, कंट्रोल प्लेन और चैनल कनेक्शन के लिए हमेशा चालू रहने वाली एक प्रक्रिया।
• इनके लिए एकल मल्टीप्लेक्स्ड पोर्ट:
  • WebSocket नियंत्रण/RPC
  • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • Plugin HTTP रूट, जैसे वैकल्पिक /api/v1/admin/rpc
  • नियंत्रण UI और हुक
• डिफ़ॉल्ट बाइंड मोड: loopback। पहचाने गए कंटेनर परिवेश के भीतर प्रभावी डिफ़ॉल्ट auto है (पोर्ट-फ़ॉरवर्डिंग के लिए 0.0.0.0 में निर्धारित होता है), जब तक Tailscale सर्व/फ़नल सक्रिय न हो, जो हमेशा loopback को बाध्य करता है।
• डिफ़ॉल्ट रूप से प्रमाणीकरण आवश्यक है। साझा-सीक्रेट सेटअप gateway.auth.token / gateway.auth.password (या OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD) का उपयोग करते हैं, और नॉन-लूपबैक रिवर्स-प्रॉक्सी सेटअप gateway.auth.mode: "trusted-proxy" का उपयोग कर सकते हैं।

OpenAI-संगत एंडपॉइंट

OpenClaw की सर्वाधिक प्रभावशाली संगतता सतह:

• GET /v1/models
• GET /v1/models/{id}
• POST /v1/embeddings
• POST /v1/chat/completions
• POST /v1/responses

यह समूह क्यों महत्वपूर्ण है:

• अधिकांश Open WebUI, LobeChat और LibreChat एकीकरण पहले /v1/models को प्रोब करते हैं।
• कई RAG और मेमोरी पाइपलाइन /v1/embeddings की अपेक्षा करती हैं।
• एजेंट-नेटिव क्लाइंट तेज़ी से /v1/responses को प्राथमिकता दे रहे हैं।

/v1/models एजेंट-प्रथम है: यह प्रत्येक कॉन्फ़िगर किए गए एजेंट के लिए openclaw, openclaw/default, और openclaw/<agentId> लौटाता है। openclaw/default स्थिर उपनाम है जो हमेशा कॉन्फ़िगर किए गए डिफ़ॉल्ट एजेंट से मैप होता है। जब बैकएंड प्रदाता/मॉडल ओवरराइड चाहिए, तब x-openclaw-model भेजें; अन्यथा चयनित एजेंट का सामान्य मॉडल और एम्बेडिंग सेटअप नियंत्रण में रहता है।

ये सभी मुख्य Gateway पोर्ट पर चलते हैं और Gateway HTTP API के शेष भाग के समान विश्वसनीय ऑपरेटर प्रमाणीकरण सीमा का उपयोग करते हैं।

एडमिन HTTP RPC (POST /api/v1/admin/rpc) ऐसे होस्ट टूलिंग के लिए एक अलग, डिफ़ॉल्ट रूप से बंद Plugin रूट है जो WebSocket RPC का उपयोग नहीं कर सकती। एडमिन HTTP RPC देखें।

पोर्ट और बाइंड की प्राथमिकता

इंस्टॉल की गई Gateway सेवाएँ निर्धारित --port को सुपरवाइज़र मेटाडेटा में दर्ज करती हैं। gateway.port बदलने के बाद, openclaw doctor --fix या openclaw gateway install --force चलाएँ, ताकि launchd/systemd/schtasks प्रक्रिया को नए पोर्ट पर शुरू करे।

नॉन-लूपबैक बाइंड के लिए स्थानीय नियंत्रण UI ऑरिजिन सीड करते समय Gateway स्टार्टअप उसी प्रभावी पोर्ट और बाइंड का उपयोग करता है। उदाहरण के लिए, रनटाइम सत्यापन चलने से पहले --bind lan --port 3000, http://localhost:3000 और http://127.0.0.1:3000 को सीड करता है। HTTPS प्रॉक्सी URL जैसे किसी भी रिमोट ब्राउज़र ऑरिजिन को gateway.controlUi.allowedOrigins में स्पष्ट रूप से जोड़ें।

हॉट रीलोड मोड

ऑपरेटर कमांड समूह

openclaw gateway statusopenclaw gateway status --deep   # सिस्टम-स्तरीय सेवा स्कैन जोड़ता हैopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep अतिरिक्त सेवा खोज (LaunchDaemons/systemd सिस्टम यूनिट/schtasks) के लिए है, अधिक गहन RPC स्थिति प्रोब के लिए नहीं।

एकाधिक Gateway (एक ही होस्ट)

अधिकांश इंस्टॉलेशन में प्रति मशीन एक Gateway चलना चाहिए। एक Gateway कई एजेंट और चैनल होस्ट कर सकता है। आपको एकाधिक Gateway की आवश्यकता केवल तब होती है जब आप जानबूझकर पृथक्करण या बचाव बॉट चाहते हैं।

उपयोगी जाँच:

openclaw gateway status --deepopenclaw gateway probe

क्या अपेक्षा करें:

• gateway status --deep Other gateway-like services detected (best effort) की रिपोर्ट कर सकता है और पुराने launchd/systemd/schtasks इंस्टॉलेशन मौजूद रहने पर सफ़ाई के संकेत दिखा सकता है।
• gateway probe अलग-अलग Gateway के उत्तर देने पर, या जब OpenClaw यह प्रमाणित नहीं कर पाता कि पहुँच-योग्य लक्ष्य एक ही Gateway हैं, तब multiple reachable gateway identities के बारे में चेतावनी दे सकता है। एक ही Gateway तक SSH टनल, प्रॉक्सी URL या कॉन्फ़िगर किया गया रिमोट URL, अलग-अलग ट्रांसपोर्ट पोर्ट होने पर भी, एकाधिक ट्रांसपोर्ट वाला एक Gateway है।
• यदि यह जानबूझकर किया गया है, तो प्रत्येक Gateway के लिए पोर्ट, कॉन्फ़िगरेशन/स्थिति और वर्कस्पेस रूट अलग रखें।

प्रत्येक इंस्टेंस की जाँच-सूची:

• अद्वितीय gateway.port
• अद्वितीय OPENCLAW_CONFIG_PATH
• अद्वितीय OPENCLAW_STATE_DIR
• अद्वितीय 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।

रिमोट एक्सेस

प्राथमिकता: Tailscale/VPN। वैकल्पिक उपाय: SSH टनल।

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

इसके बाद क्लाइंट को स्थानीय रूप से ws://127.0.0.1:18789 से कनेक्ट करें।

देखें: रिमोट Gateway, प्रमाणीकरण, Tailscale।

पर्यवेक्षण और सेवा जीवनचक्र

प्रोडक्शन-जैसी विश्वसनीयता के लिए पर्यवेक्षित रन का उपयोग करें।

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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=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

अमान्य कॉन्फ़िगरेशन त्रुटियाँ 78 कोड के साथ बाहर निकलती हैं। कॉन्फ़िगरेशन ठीक होने तक पुनः लॉन्च रोकने के लिए Linux systemd यूनिट RestartPreventExitStatus=78 का उपयोग करती हैं। launchd और Windows Task Scheduler में प्रति-एग्ज़िट-कोड रोकने का समकक्ष नियम नहीं है, इसलिए Gateway तेज़ अस्वच्छ बूट इतिहास को भी स्थायी रूप से संग्रहीत करता है और बार-बार स्टार्टअप विफलताओं के बाद चैनल/प्रदाता खाते का स्वतः-स्टार्ट रोक देता है। उस सुरक्षित मोड में कंट्रोल प्लेन निरीक्षण और सुधार के लिए फिर भी शुरू होता है, कॉन्फ़िगरेशन हॉट रीलोड और secrets.reload स्वचालित चैनल पुनः शुरू करने से इनकार करते हैं, और ऑपरेटर का स्पष्ट channels.start अनुरोध इस रोक को ओवरराइड कर सकता है।

डेवलपमेंट प्रोफ़ाइल का त्वरित पथ

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

डिफ़ॉल्ट में पृथक स्थिति/कॉन्फ़िगरेशन और आधार Gateway पोर्ट 19001 शामिल हैं।

प्रोटोकॉल त्वरित संदर्भ (ऑपरेटर दृश्य)

• पहला क्लाइंट फ़्रेम connect होना चाहिए।
• Gateway एक hello-ok फ़्रेम लौटाता है, जिसमें snapshot (presence, health, stateVersion, uptimeMs) के साथ policy सीमाएँ (maxPayload, maxBufferedBytes, tickIntervalMs) होती हैं।
• hello-ok.features.methods / events एक रूढ़िवादी खोज सूची है, प्रत्येक कॉल किए जा सकने वाले सहायक रूट का जनरेट किया गया डंप नहीं।
• अनुरोध: req(method, params) → res(ok/payload|error)।
• सामान्य इवेंट में connect.challenge, agent, chat, session.message, session.operation, session.tool, ऑप्ट-इन session.approval, sessions.changed, presence, tick, health, heartbeat, पेयरिंग/अनुमोदन जीवनचक्र इवेंट और shutdown शामिल हैं।

एजेंट रन दो चरणों में होते हैं:

1. तत्काल स्वीकृति की अभिस्वीकृति (status:"accepted")
2. अंतिम पूर्णता प्रतिक्रिया (status:"ok"|"error"), जिनके बीच agent इवेंट स्ट्रीम किए जाते हैं।

संपूर्ण प्रोटोकॉल दस्तावेज़ देखें: Gateway प्रोटोकॉल।

परिचालन जाँच

सक्रियता

• WS खोलें और connect भेजें।
• स्नैपशॉट सहित hello-ok प्रतिक्रिया अपेक्षित है।

तत्परता

openclaw gateway statusopenclaw channels status --probeopenclaw health

अंतराल से पुनर्प्राप्ति

इवेंट दोबारा नहीं चलाए जाते। अनुक्रम में अंतराल होने पर, जारी रखने से पहले स्थिति (health, system-presence) रीफ़्रेश करें।

विफलता के सामान्य संकेत

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

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

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

संबंधित

• कॉन्फ़िगरेशन
• Gateway समस्या निवारण
• पृष्ठभूमि प्रक्रिया
• स्वास्थ्य
• डॉक्टर
• प्रमाणीकरण
• रिमोट एक्सेस
• सीक्रेट प्रबंधन