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 serve/funnel सक्रिय न हो, जो हमेशा 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 समस्या-निवारण
• बैकग्राउंड प्रक्रिया
• स्वास्थ्य
• Doctor
• प्रमाणीकरण
• रिमोट एक्सेस
• सीक्रेट प्रबंधन