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

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

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

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

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

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

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

सीक्रेट योजना अनुबंध

सटीक secrets apply लक्ष्य/पथ नियम और केवल-रेफ़रेंस ऑथ-प्रोफ़ाइल व्यवहार।

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

1

Gateway शुरू करें

2

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

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

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

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

​
रनटाइम मॉडल

  • रूटिंग, कंट्रोल प्लेन और चैनल कनेक्शन के लिए हमेशा चालू रहने वाली एक प्रक्रिया।
  • इनके लिए एकल मल्टीप्लेक्स्ड पोर्ट:
    • 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 में स्पष्ट रूप से जोड़ें।

​
हॉट रीलोड मोड

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

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

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

अधिकांश इंस्टॉलेशन में प्रति मशीन एक Gateway चलना चाहिए। एक Gateway कई एजेंट और चैनल होस्ट कर सकता है। आपको एकाधिक Gateway की आवश्यकता केवल तब होती है जब आप जानबूझकर पृथक्करण या बचाव बॉट चाहते हैं। उपयोगी जाँच:
क्या अपेक्षा करें:
  • 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
उदाहरण:
विस्तृत सेटअप: /gateway/multiple-gateways।

​
रिमोट एक्सेस

प्राथमिकता: Tailscale/VPN। वैकल्पिक उपाय: SSH टनल।
इसके बाद क्लाइंट को स्थानीय रूप से ws://127.0.0.1:18789 से कनेक्ट करें।
SSH टनल Gateway प्रमाणीकरण को बायपास नहीं करतीं। साझा-सीक्रेट प्रमाणीकरण के लिए, क्लाइंट को टनल पर भी token/password भेजना आवश्यक है। पहचान-युक्त मोड के लिए, अनुरोध को फिर भी उस प्रमाणीकरण पथ को संतुष्ट करना होगा।
देखें: रिमोट Gateway, प्रमाणीकरण, Tailscale।

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

प्रोडक्शन-जैसी विश्वसनीयता के लिए पर्यवेक्षित रन का उपयोग करें।
पुनः शुरू करने के लिए openclaw gateway restart का उपयोग करें। पुनः शुरू करने के विकल्प के रूप में openclaw gateway stop और openclaw gateway start को क्रमबद्ध न करें।macOS पर, gateway stop डिफ़ॉल्ट रूप से launchctl bootout का उपयोग करता है। यह LaunchAgent को स्थायी रूप से अक्षम किए बिना वर्तमान बूट सत्र से हटा देता है, इसलिए अप्रत्याशित क्रैश के बाद KeepAlive स्वतः-पुनर्प्राप्ति काम करती रहती है और gateway start इसे सुव्यवस्थित रूप से फिर सक्षम करता है। रीबूट के दौरान स्वतः-पुनःस्पॉन को स्थायी रूप से रोकने के लिए, --disable पास करें: openclaw gateway stop --disable।LaunchAgent लेबल ai.openclaw.gateway (डिफ़ॉल्ट) या ai.openclaw.<profile> (नामित प्रोफ़ाइल) होते हैं। openclaw doctor सेवा कॉन्फ़िगरेशन विचलन का ऑडिट और सुधार करता है।
अमान्य कॉन्फ़िगरेशन त्रुटियाँ 78 कोड के साथ बाहर निकलती हैं। कॉन्फ़िगरेशन ठीक होने तक पुनः लॉन्च रोकने के लिए Linux systemd यूनिट RestartPreventExitStatus=78 का उपयोग करती हैं। launchd और Windows Task Scheduler में प्रति-एग्ज़िट-कोड रोकने का समकक्ष नियम नहीं है, इसलिए Gateway तेज़ अस्वच्छ बूट इतिहास को भी स्थायी रूप से संग्रहीत करता है और बार-बार स्टार्टअप विफलताओं के बाद चैनल/प्रदाता खाते का स्वतः-स्टार्ट रोक देता है। उस सुरक्षित मोड में कंट्रोल प्लेन निरीक्षण और सुधार के लिए फिर भी शुरू होता है, कॉन्फ़िगरेशन हॉट रीलोड और secrets.reload स्वचालित चैनल पुनः शुरू करने से इनकार करते हैं, और ऑपरेटर का स्पष्ट channels.start अनुरोध इस रोक को ओवरराइड कर सकता है।

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

डिफ़ॉल्ट में पृथक स्थिति/कॉन्फ़िगरेशन और आधार 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 प्रतिक्रिया अपेक्षित है।

​
तत्परता

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

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

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

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

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

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

​
संबंधित