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

यह विस्तृत रनबुक है। पहले त्वरित ट्रायेज प्रवाह के लिए /सहायता/समस्या निवारण से शुरू करें।

कमांड क्रम

इस क्रम में चलाएँ:

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

सही स्थिति के संकेत:

• openclaw gateway status में Runtime: running, Connectivity probe: ok, और एक Capability: ... पंक्ति दिखाई देती है।
• openclaw doctor किसी अवरोधक कॉन्फ़िगरेशन/सेवा समस्या की रिपोर्ट नहीं करता।
• openclaw channels status --probe प्रत्येक अकाउंट की सक्रिय ट्रांसपोर्ट स्थिति और जहाँ समर्थित हो, works या audit ok दिखाता है।

अपडेट के बाद

जब अपडेट पूरा हो जाए, लेकिन Gateway बंद हो, चैनल खाली हों, या मॉडल कॉल 401 त्रुटियों के साथ विफल हों, तब इसका उपयोग करें।

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw gateway restart

इनकी जाँच करें:

• openclaw status / openclaw status --all में Update restart। लंबित या विफल हैंडऑफ़ में चलाने वाला अगला कमांड शामिल होता है।
• चैनल के अंतर्गत plugin load failed: dependency tree corrupted; run openclaw doctor --fix: चैनल कॉन्फ़िगरेशन अभी भी मौजूद है, लेकिन चैनल लोड होने से पहले Plugin पंजीकरण विफल हो गया।
• दोबारा प्रमाणीकरण के बाद प्रदाता की 401 त्रुटियाँ: openclaw doctor --fix पुराने प्रति-एजेंट OAuth प्रमाणीकरण शैडो की जाँच करता है और पुरानी प्रतियाँ हटा देता है, ताकि सभी एजेंट वर्तमान साझा प्रोफ़ाइल का समाधान करें।

विभाजित इंस्टॉलेशन और नए कॉन्फ़िगरेशन की सुरक्षा

जब अपडेट के बाद कोई Gateway सेवा अप्रत्याशित रूप से बंद हो जाए, या लॉग दिखाएँ कि एक openclaw बाइनरी उस संस्करण से पुरानी है जिसने अंतिम बार openclaw.json लिखा था, तब इसका उपयोग करें।

OpenClaw कॉन्फ़िगरेशन लेखन पर meta.lastTouchedVersion की मुहर लगाता है। केवल-पढ़ने वाले कमांड नए OpenClaw द्वारा लिखे गए कॉन्फ़िगरेशन का निरीक्षण कर सकते हैं, लेकिन पुरानी बाइनरी से प्रक्रिया और सेवा में बदलाव करने से मना कर दिया जाता है। अवरुद्ध कार्रवाइयाँ: Gateway सेवा शुरू/बंद/पुनः आरंभ/अनइंस्टॉल करना, सेवा को बलपूर्वक पुनः इंस्टॉल करना, सेवा-मोड में Gateway शुरू करना, और gateway --force पोर्ट की सफ़ाई।

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

रोलबैक के बाद प्रोटोकॉल बेमेल

जब डाउनग्रेड या रोलबैक के बाद लॉग में लगातार protocol mismatch दिखाई दे, तब इसका उपयोग करें। एक पुराना Gateway चल रहा है, लेकिन एक नई स्थानीय क्लाइंट प्रक्रिया अभी भी ऐसी प्रोटोकॉल सीमा के साथ दोबारा कनेक्ट हो रही है जिसे पुराना Gateway समझ नहीं सकता।

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw logs --follow

इनकी जाँच करें:

• Gateway लॉग में protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>।
• openclaw gateway status --deep में Established clients: या openclaw doctor --deep में Gateway clients: Gateway पोर्ट से जुड़े सक्रिय TCP क्लाइंट, और ऑपरेटिंग सिस्टम की अनुमति होने पर PID तथा कमांड पंक्तियाँ।
• ऐसी क्लाइंट प्रक्रिया जिसकी कमांड पंक्ति उस नए OpenClaw इंस्टॉलेशन या रैपर की ओर संकेत करती है जिससे आपने रोलबैक किया था।

समाधान:

1. gateway status --deep द्वारा दिखाई गई पुरानी OpenClaw क्लाइंट प्रक्रिया को बंद या पुनः आरंभ करें।
2. OpenClaw को एम्बेड करने वाले ऐप या रैपर पुनः आरंभ करें: स्थानीय डैशबोर्ड, एडिटर, ऐप-सर्वर सहायक, या लंबे समय से चल रहे openclaw logs --follow शेल।
3. openclaw gateway status --deep या openclaw doctor --deep दोबारा चलाएँ और पुष्टि करें कि पुराना क्लाइंट PID हट गया है।

किसी पुराने Gateway को नया असंगत प्रोटोकॉल स्वीकार करने योग्य न बनाएँ। प्रोटोकॉल वृद्धि वायर अनुबंध की सुरक्षा करती है; रोलबैक पुनर्प्राप्ति प्रक्रिया/संस्करण की सफ़ाई की समस्या है।

पथ से बाहर निकलने के कारण Skill सिमलिंक छोड़ा गया

जब लॉग में यह शामिल हो, तब इसका उपयोग करें:

कॉन्फ़िगर किए गए रूट से बाहर निकला Skill पथ छोड़ा जा रहा है: ... reason=symlink-escape

प्रत्येक Skill रूट एक परिरोधन सीमा है। ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills, या ~/.openclaw/skills के अंतर्गत कोई सिमलिंक तब छोड़ दिया जाता है जब उसका वास्तविक लक्ष्य उस रूट से बाहर समाधान होता है, जब तक कि लक्ष्य स्पष्ट रूप से विश्वसनीय न हो।

लिंक का निरीक्षण करें:

ls -l ~/.agents/skills/<name>realpath ~/.agents/skills/<name>openclaw config get skills.load

यदि लक्ष्य जानबूझकर निर्धारित किया गया है, तो प्रत्यक्ष Skill रूट और अनुमत सिमलिंक लक्ष्य दोनों कॉन्फ़िगर करें:

{  skills: {    load: {      extraDirs: ["~/Projects/manager/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],    },  },}

फिर नया सत्र शुरू करें या Skills वॉचर के रीफ़्रेश होने की प्रतीक्षा करें। यदि चल रही प्रक्रिया कॉन्फ़िगरेशन परिवर्तन से पहले की है, तो Gateway पुनः आरंभ करें।

~, /, या पूरा सिंक किया हुआ प्रोजेक्ट फ़ोल्डर जैसे व्यापक लक्ष्यों का उपयोग न करें। allowSymlinkTargets को उस वास्तविक Skill रूट तक सीमित रखें जिसमें विश्वसनीय SKILL.md डायरेक्टरियाँ हैं।

यदि Skill Workshop का लागू करना भी उन विश्वसनीय सिमलिंक वाली वर्कस्पेस Skill पथों के माध्यम से लिखना चाहिए, तो skills.workshop.allowSymlinkTargetWrites सक्षम करें। केवल-पढ़ने वाले साझा Skill रूट के लिए इसे अक्षम रखें।

संबंधित:

• Skills कॉन्फ़िगरेशन
• कॉन्फ़िगरेशन के उदाहरण

लंबे कॉन्टेक्स्ट के लिए Anthropic 429 अतिरिक्त उपयोग आवश्यक

जब लॉग/त्रुटियों में यह शामिल हो, तब इसका उपयोग करें: HTTP 429: rate_limit_error: Extra usage is required for long context requests।

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

इनकी जाँच करें:

• चयनित Anthropic मॉडल GA-सक्षम 1M Claude 4.x मॉडल (Opus 4.6/4.7/4.8, Sonnet 4.6) है, या मॉडल कॉन्फ़िगरेशन में अभी भी पुराना params.context1m: true मौजूद है।
• वर्तमान Anthropic क्रेडेंशियल लंबे कॉन्टेक्स्ट के उपयोग के लिए पात्र नहीं है।
• अनुरोध केवल लंबे सत्रों/मॉडल रन पर विफल होते हैं जिन्हें 1M कॉन्टेक्स्ट पथ की आवश्यकता होती है।

समाधान विकल्प:

संबंधित:

• Anthropic
• टोकन उपयोग और लागत
• मुझे Anthropic से HTTP 429 क्यों दिखाई दे रहा है?

अपस्ट्रीम 403 अवरुद्ध प्रतिक्रियाएँ

जब कोई अपस्ट्रीम LLM प्रदाता Your request was blocked जैसी सामान्य 403 लौटाए, तब इसका उपयोग करें।

यह न मानें कि यह हमेशा OpenClaw कॉन्फ़िगरेशन की समस्या है। प्रतिक्रिया किसी अपस्ट्रीम सुरक्षा परत से आ सकती है, जैसे CDN, WAF, बॉट-प्रबंधन नियम, या OpenAI-संगत एंडपॉइंट के सामने स्थित रिवर्स प्रॉक्सी।

openclaw statusopenclaw gateway statusopenclaw logs --follow

इनकी जाँच करें:

• एक ही प्रदाता के अंतर्गत कई मॉडल एक ही प्रकार से विफल हो रहे हैं।
• सामान्य प्रदाता API त्रुटि के बजाय HTML या सामान्य सुरक्षा पाठ।
• उसी अनुरोध समय के लिए प्रदाता-पक्ष की सुरक्षा घटनाएँ।
• एक छोटा प्रत्यक्ष curl प्रोब सफल होता है, जबकि सामान्य SDK-आकार के अनुरोध विफल होते हैं।

जब साक्ष्य WAF/CDN अवरोध की ओर संकेत करें, तो पहले प्रदाता-पक्ष की फ़िल्टरिंग ठीक करें। OpenClaw द्वारा उपयोग किए जाने वाले API पथ के लिए सीमित दायरे वाला अनुमति या स्किप नियम पसंद करें, और पूरी साइट के लिए सुरक्षा अक्षम करने से बचें।

संबंधित:

• OpenAI-संगत एंडपॉइंट
• प्रदाता कॉन्फ़िगरेशन
• लॉग

स्थानीय OpenAI-संगत बैकएंड प्रत्यक्ष प्रोब पास करता है, लेकिन एजेंट रन विफल होते हैं

इस स्थिति में उपयोग करें:

• curl ... /v1/models काम करता है।
• छोटे प्रत्यक्ष /v1/chat/completions कॉल काम करते हैं।
• OpenClaw मॉडल रन केवल सामान्य एजेंट टर्न पर विफल होते हैं।

curl http://127.0.0.1:1234/v1/modelscurl http://127.0.0.1:1234/v1/chat/completions \  -H 'content-type: application/json' \  -d '{"model":"<id>","messages":[{"role":"user","content":"नमस्ते"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "नमस्ते" --jsonopenclaw logs --follow

इनकी जाँच करें:

• प्रत्यक्ष छोटे कॉल सफल होते हैं, लेकिन OpenClaw रन केवल बड़े प्रॉम्प्ट पर विफल होते हैं।
• model_not_found या 404 त्रुटियाँ, भले ही प्रत्यक्ष /v1/chat/completions उसी मूल मॉडल आईडी के साथ काम करता हो।
• messages[].content द्वारा स्ट्रिंग अपेक्षित होने से संबंधित बैकएंड त्रुटियाँ।
• OpenAI-संगत स्थानीय बैकएंड के साथ रुक-रुक कर आने वाली incomplete turn detected ... stopReason=stop payloads=0 चेतावनियाँ।
• बैकएंड क्रैश जो केवल अधिक प्रॉम्प्ट-टोकन संख्या या पूरे एजेंट रनटाइम प्रॉम्प्ट के साथ दिखाई देते हैं।

संबंधित:

• कॉन्फ़िगरेशन
• स्थानीय मॉडल
• OpenAI-संगत एंडपॉइंट

कोई उत्तर नहीं

यदि चैनल चालू हैं, लेकिन कोई उत्तर नहीं मिल रहा है, तो कुछ भी दोबारा कनेक्ट करने से पहले रूटिंग और नीति जाँचें।

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

इनकी जाँच करें:

• DM प्रेषकों के लिए पेयरिंग लंबित है।
• समूह में उल्लेख की शर्त (requireMention, mentionPatterns)।
• चैनल/समूह अनुमति-सूची में असंगतियाँ।

सामान्य संकेत:

• drop guild message (mention required → उल्लेख किए जाने तक समूह संदेश की उपेक्षा की गई।
• pairing request → प्रेषक को अनुमोदन चाहिए।
• blocked / allowlist → प्रेषक/चैनल को नीति द्वारा फ़िल्टर किया गया।

संबंधित:

• चैनल समस्या-निवारण
• समूह
• पेयरिंग

डैशबोर्ड नियंत्रण UI कनेक्टिविटी

जब डैशबोर्ड/नियंत्रण UI कनेक्ट न हो, तो URL, प्रमाणीकरण मोड और सुरक्षित संदर्भ से जुड़ी मान्यताओं को सत्यापित करें।

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

इनकी जाँच करें:

• सही जाँच URL और डैशबोर्ड URL।
• क्लाइंट और Gateway के बीच प्रमाणीकरण मोड/टोकन में असंगति।
• जहाँ डिवाइस पहचान आवश्यक है, वहाँ HTTP का उपयोग।

यदि किसी अपडेट के बाद स्थानीय ब्राउज़र 127.0.0.1:18789 से कनेक्ट नहीं हो पा रहा है, तो पहले स्थानीय Gateway सेवा को पुनः चालू करें और पुष्टि करें कि वह डैशबोर्ड उपलब्ध करा रही है:

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

यदि curl OpenClaw HTML लौटाता है, तो Gateway काम कर रहा है और शेष समस्या संभवतः ब्राउज़र कैश, किसी पुराने डीप लिंक या पुराने टैब की स्थिति से जुड़ी है। http://127.0.0.1:18789 को सीधे खोलें और डैशबोर्ड से आगे जाएँ। यदि पुनः आरंभ करने के बाद सेवा चालू नहीं रहती, तो openclaw gateway start चलाएँ और openclaw gateway status दोबारा जाँचें।

प्रमाणीकरण विवरण कोड का त्वरित मानचित्र

अगली कार्रवाई चुनने के लिए विफल connect प्रतिक्रिया से error.details.code का उपयोग करें:

डिवाइस प्रमाणीकरण v2 माइग्रेशन जाँच:

openclaw --versionopenclaw doctoropenclaw gateway status

यदि लॉग नॉन्स/हस्ताक्षर त्रुटियाँ दिखाते हैं, तो कनेक्ट होने वाले क्लाइंट को अपडेट करें और उसे सत्यापित करें:

यदि openclaw devices rotate / revoke / remove को अप्रत्याशित रूप से अस्वीकार किया जाता है:

• पेयर किए गए डिवाइस की टोकन-सत्र केवल अपने स्वयं के डिवाइस को प्रबंधित कर सकते हैं, जब तक कॉलर के पास operator.admin भी न हो।
• openclaw devices rotate --scope ... केवल उन्हीं ऑपरेटर स्कोप का अनुरोध कर सकता है जो कॉलर सत्र के पास पहले से हैं।

संबंधित:

• कॉन्फ़िगरेशन (Gateway प्रमाणीकरण मोड)
• नियंत्रण UI
• डिवाइस
• दूरस्थ पहुँच
• विश्वसनीय प्रॉक्सी प्रमाणीकरण

Gateway सेवा चालू नहीं है

जब सेवा इंस्टॉल हो, लेकिन प्रक्रिया चालू न रहे, तब इसका उपयोग करें।

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # सिस्टम-स्तरीय सेवाओं को भी स्कैन करें

इनकी जाँच करें:

• Runtime: stopped के साथ निकास संकेत।
• सेवा कॉन्फ़िगरेशन में असंगति (Config (cli) बनाम Config (service))।
• पोर्ट/लिसनर टकराव।
• --deep का उपयोग होने पर अतिरिक्त launchd/systemd/schtasks इंस्टॉलेशन।
• Other gateway-like services detected (best effort) के सफ़ाई संकेत।

संबंधित:

• पृष्ठभूमि निष्पादन और प्रक्रिया टूल
• कॉन्फ़िगरेशन
• Doctor

macOS Gateway चुपचाप प्रत्युत्तर देना बंद कर देता है, फिर डैशबोर्ड को छूने पर दोबारा शुरू हो जाता है

जब macOS होस्ट पर चैनल (Telegram, WhatsApp आदि) एक बार में कई मिनटों से लेकर कई घंटों तक निष्क्रिय हो जाएँ और आपके Control UI खोलते ही, SSH से कनेक्ट करते ही या होस्ट से किसी अन्य तरीके से इंटरैक्ट करते ही Gateway फिर से चालू होता दिखाई दे, तब इसका उपयोग करें। आम तौर पर openclaw status में कोई स्पष्ट लक्षण नहीं दिखता, क्योंकि जब तक आप जाँचते हैं, Gateway फिर से सक्रिय हो चुका होता है।

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"

इनकी जाँच करें:

• ~/.openclaw/logs/stability/ में एक या अधिक *-uncaught_exception.json बंडल, जिनमें error.code को ENETDOWN, ENETUNREACH, EHOSTUNREACH या ECONNREFUSED जैसे अस्थायी नेटवर्क कोड पर सेट किया गया हो।
• क्रैश टाइमस्टैम्प से मेल खाती Entering Sleep state due to 'Maintenance Sleep' या en0 driver is slow (msg: WillChangeState to 0) जैसी pmset -g log पंक्तियाँ। Power Nap / Maintenance Sleep कुछ समय के लिए Wi-Fi ड्राइवर को स्थिति 0 में डाल देता है; उस अवधि में होने वाला कोई भी आउटबाउंड connect(), सामान्यतः पूर्ण नेटवर्क कनेक्टिविटी वाले होस्ट पर भी ENETDOWN के साथ विफल हो सकता है।
• launchctl print आउटपुट, जिसमें हाल के कई runs और एक एग्ज़िट कोड के साथ state = not running दिखाई दे, विशेष रूप से जब क्रैश और अगले लॉन्च के बीच का अंतर सेकंड के बजाय लगभग एक घंटे का हो। macOS launchd क्रैश की शृंखला के बाद एक गैर-दस्तावेज़ीकृत री-स्पॉन सुरक्षा गेट लागू करता है, जिसके कारण इंटरैक्टिव लॉगिन, डैशबोर्ड कनेक्शन या launchctl kickstart जैसे किसी बाहरी ट्रिगर द्वारा उसे फिर से सक्रिय किए जाने तक वह KeepAlive=true का पालन करना बंद कर सकता है।

सामान्य संकेत:

• ऐसा स्थिरता बंडल जिसका error.code, ENETDOWN या कोई संबंधित कोड हो और कॉल स्टैक Node net lookupAndConnect / Socket.connect की ओर इंगित करे। OpenClaw 2026.5.26 और उसके बाद के संस्करण इन्हें हानिरहित अस्थायी नेटवर्क त्रुटियों के रूप में वर्गीकृत करते हैं, इसलिए अब ये शीर्ष-स्तरीय अनकॉट हैंडलर तक नहीं पहुँचतीं; यदि आप कोई पुराना रिलीज़ उपयोग कर रहे हैं, तो पहले अपग्रेड करें।
• लंबी निष्क्रिय अवधियाँ, जो आपके Control UI से कनेक्ट करते ही या होस्ट में SSH करते ही समाप्त हो जाती हैं: उपयोगकर्ता को दिखाई देने वाली गतिविधि ही launchd के री-स्पॉन गेट को फिर से सक्रिय करती है, न कि डैशबोर्ड द्वारा Gateway पर की गई कोई कार्रवाई।
• पूरे दिन runs की संख्या बढ़ती रहे, लेकिन ~/Library/Logs/openclaw/gateway.log में उससे संबंधित कोई received SIG*; shutting down पंक्ति न हो: स्वच्छ शटडाउन में सिग्नल लॉग होता है; अस्थायी क्रैश में नहीं।

क्या करें:

1. यदि आप 2026.5.26 से पहले का रिलीज़ चला रहे हैं, तो Gateway अपग्रेड करें। अपग्रेड करने के बाद, भविष्य की ENETDOWN त्रुटियाँ प्रक्रिया समाप्त करने के बजाय चेतावनियों के रूप में लॉग की जाएँगी।

2. हमेशा चालू सर्वर के रूप में चलने वाले Mac mini / डेस्कटॉप होस्ट पर मेंटेनेंस स्लीप गतिविधि कम करें:

   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0

   इससे अंतर्निहित ड्राइवर अस्थिरता काफ़ी कम होती है, लेकिन पूरी तरह समाप्त नहीं होती। इन फ़्लैग के बावजूद सिस्टम TCP कीपअलाइव और mDNS रखरखाव के लिए कुछ मेंटेनेंस स्लीप अभी भी कर सकता है।

3. सक्रियता वॉचडॉग जोड़ें, ताकि भविष्य में क्रैश की शृंखला के बाद launchd द्वारा रोकी गई प्रक्रिया का तुरंत पता लगाया जा सके:

   # launchd की जानकारी रखने वाली सक्रियता जाँच का उदाहरण, 5-मिनट के cron या LaunchAgent के लिए उपयुक्तstate=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')if [ "$state" != "running" ]; then  launchctl kickstart -k gui/$UID/ai.openclaw.gatewayfi

   उद्देश्य री-स्पॉन गेट को बाहरी रूप से फिर से सक्रिय करना है; क्रैश की शृंखला के बाद macOS पर केवल KeepAlive=true पर्याप्त नहीं है।

संबंधित:

• macOS प्लेटफ़ॉर्म नोट्स
• लॉगिंग
• Doctor

डुप्लिकेट Gateway/Node LaunchAgents के साथ macOS launchd सुपरवाइज़र लूप

इसका उपयोग तब करें, जब कोई macOS इंस्टॉलेशन हर कुछ सेकंड में पुनः आरंभ होता रहे, openclaw स्वास्थ्य जाँच स्वस्थ और अनुपलब्ध स्थितियों के बीच बदलती रहे और चैनल डिस्पैच रुक जाए, भले ही सेवा चलती हुई दिखाई दे।

यह ऐसे पुराने इंस्टॉलेशन पर देखा गया था, जहाँ ai.openclaw.gateway और ai.openclaw.node दोनों LaunchAgents सक्रिय थे और प्रत्येक OPENCLAW_LAUNCHD_LABEL इंजेक्ट करता था। इस स्थिति में OpenClaw launchd पर्यवेक्षण का पता लगा सकता है, पुनः आरंभ का नियंत्रण launchd को लौटाने का प्रयास कर सकता है और एक स्थिर Gateway प्रक्रिया के बजाय तेज़ EADDRINUSE/री-स्पॉन लूप में फँस सकता है।

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'tail -n 80 ~/Library/Logs/openclaw/gateway.log

इनकी जाँच करें:

• 30-सेकंड के नमूने में एक स्थिर प्रक्रिया के बजाय एक से अधिक Gateway PID।
• gateway.log में EADDRINUSE, another gateway instance is already listening या बार-बार दिखाई देने वाली पुनः आरंभ/हैंडऑफ़ पंक्तियाँ।
• ऐसे होस्ट पर ~/Library/LaunchAgents/ai.openclaw.gateway.plist और ~/Library/LaunchAgents/ai.openclaw.node.plist दोनों एक साथ लोड हों, जहाँ केवल एक प्रबंधित Gateway सेवा चलनी चाहिए।

क्या करें:

1. यदि इस होस्ट पर केवल Gateway सेवा चलनी चाहिए, तो OpenClaw के माध्यम से प्रबंधित Node सेवा हटाएँ। यदि आप रिमोट Node सुविधाओं के लिए Node सेवा पर सक्रिय रूप से निर्भर हैं, तो यह चरण छोड़ दें; इसे अनइंस्टॉल करने से इस होस्ट पर वे सुविधाएँ बंद हो जाती हैं:

   openclaw node uninstall

2. एक स्थायी Gateway रैपर इंस्टॉल करें, जो OpenClaw शुरू करने से पहले इनहेरिट किए गए launchd मार्कर साफ़ करे। समर्थित --wrapper विकल्प का उपयोग करें; ~/.openclaw/service-env/ के अंतर्गत जनरेट की गई फ़ाइल संपादित न करें, क्योंकि सेवा पुनः इंस्टॉल, अपडेट और Doctor मरम्मत उस फ़ाइल को दोबारा जनरेट करते हैं:

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

   gateway install बाध्य पुनः इंस्टॉल, अपडेट और doctor मरम्मत के दौरान रैपर पथ को बनाए रखता है।

3. सत्यापित करें कि Gateway स्थिर है और RPC प्रदान कर रहा है, न कि केवल सुन रहा है:

   openclaw gateway status --deep --require-rpc for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done

   PID नमूने में बदलते रहने वाले PID के समूह के बजाय एक स्थिर प्रक्रिया दिखनी चाहिए, और इनबाउंड चैनल डिस्पैच फिर से शुरू हो जाना चाहिए।

4. उस रिलीज़ में अपग्रेड करने के बाद, जिसमें अंतर्निहित दोहरा-LaunchAgent लूप ठीक हो चुका है, इस समाधान को हटाएँ और सामान्य प्रबंधित सेवा को फिर से इंस्टॉल करें:

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

संबंधित:

• macOS प्लेटफ़ॉर्म नोट्स
• Doctor
• Gateway CLI

अधिक मेमोरी उपयोग के दौरान Gateway बंद हो जाता है

इसका उपयोग तब करें जब लोड के दौरान Gateway गायब हो जाए, पर्यवेक्षक OOM-जैसे पुनः आरंभ की रिपोर्ट करे, या लॉग में critical memory pressure bundle written का उल्लेख हो।

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw gateway diagnostics export

इनकी तलाश करें:

• नवीनतम स्थिरता बंडल में Reason: diagnostic.memory.pressure.critical।
• critical/rss_threshold, critical/heap_threshold, या critical/rss_growth के साथ Memory pressure:।
• हीप सीमा के पास V8 heap: मान।
• agents/<agent>/sessions/<session>.jsonl या sessions/<session>.jsonl जैसी Largest session files: प्रविष्टियाँ।
• जब Gateway किसी कंटेनर या मेमोरी-सीमित सेवा के अंदर चलता है, तब Linux cgroup मेमोरी काउंटर।

सामान्य संकेत:

• critical memory pressure bundle written पुनः आरंभ से कुछ समय पहले दिखाई देता है → OpenClaw ने OOM से पहले का स्थिरता बंडल कैप्चर किया। openclaw gateway stability --bundle latest से उसका निरीक्षण करें।
• memory pressure: level=critical Gateway लॉग में दिखाई देता है → OpenClaw ने गंभीर मेमोरी दबाव का पता लगाया और प्रक्रिया के भीतर उपलब्ध मेमोरी तथ्यों को रिकॉर्ड किया।
• Largest session files: एक बहुत बड़े संशोधित ट्रांसक्रिप्ट पथ की ओर संकेत करता है → बनाए रखे गए सत्र इतिहास को कम करें, सत्र वृद्धि का निरीक्षण करें, या पुनः आरंभ करने से पहले पुराने ट्रांसक्रिप्ट को सक्रिय स्टोर से बाहर ले जाएँ।
• V8 heap: प्रयुक्त बाइट्स हीप सीमा के करीब हैं → पहले प्रॉम्प्ट/सत्र दबाव कम करें या समवर्ती कार्य घटाएँ। प्रबंधित सेवा के लिए, openclaw gateway status में Gateway heap: का निरीक्षण करें; यदि उसमें not set लिखा है, तो openclaw gateway install --force से पुराना सेवा मेटाडेटा फिर से जनरेट करें। परिवेशी शेल NODE_OPTIONS को जानबूझकर अनदेखा किया जाता है। निरंतर कार्यभार की पुष्टि करने और पर्याप्त नेटिव-मेमोरी गुंजाइश छोड़ने के बाद ही स्पष्ट पर्यवेक्षक-स्तरीय हीप ओवरराइड का उपयोग करें।
• Memory pressure: critical/rss_growth → एक सैंपलिंग विंडो के भीतर मेमोरी तेज़ी से बढ़ी। किसी बड़े आयात, अनियंत्रित टूल आउटपुट, बार-बार पुनः प्रयास, या कतारबद्ध एजेंट कार्यों के बैच के लिए नवीनतम लॉग जाँचें।
• लॉग में गंभीर मेमोरी दबाव दिखाई देता है, लेकिन कोई बंडल मौजूद नहीं है → उपलब्ध परिचालन साक्ष्य के लिए घटना के बाद openclaw gateway diagnostics export कैप्चर करें।

स्थिरता बंडल पेलोड-रहित है। इसमें परिचालन मेमोरी साक्ष्य और संशोधित सापेक्ष फ़ाइल पथ होते हैं, संदेश टेक्स्ट, Webhook बॉडी, क्रेडेंशियल, टोकन, कुकी या अपरिष्कृत सत्र आईडी नहीं। अपरिष्कृत लॉग कॉपी करने के बजाय बग रिपोर्ट में डायग्नोस्टिक्स एक्सपोर्ट संलग्न करें।

संबंधित:

• Gateway स्वास्थ्य
• डायग्नोस्टिक्स एक्सपोर्ट
• सत्र

Gateway ने अमान्य कॉन्फ़िगरेशन अस्वीकार किया

इसका उपयोग तब करें जब Gateway स्टार्टअप Invalid config के साथ विफल हो या हॉट रीलोड लॉग बताएँ कि उसने अमान्य संपादन छोड़ दिया।

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

इनकी तलाश करें:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• सक्रिय कॉन्फ़िगरेशन के पास टाइमस्टैम्प वाली openclaw.json.rejected.* फ़ाइल।
• यदि doctor --fix ने टूटे हुए प्रत्यक्ष संपादन की मरम्मत की है, तो टाइमस्टैम्प वाली openclaw.json.clobbered.* फ़ाइल।
• OpenClaw प्रत्येक कॉन्फ़िगरेशन पथ के लिए नवीनतम 32 .clobbered.* फ़ाइलें रखता है और पुरानी फ़ाइलों को रोटेट करता है।

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

संबंधित:

• कॉन्फ़िग
• कॉन्फ़िगरेशन: हॉट रीलोड
• कॉन्फ़िगरेशन: सख्त सत्यापन
• Doctor

Gateway प्रोब चेतावनियाँ

इसका उपयोग तब करें जब openclaw gateway probe किसी चीज़ तक पहुँचता हो, लेकिन फिर भी चेतावनी ब्लॉक प्रिंट करता हो।

openclaw gateway probeopenclaw gateway probe --jsonopenclaw gateway probe --ssh user@gateway-host

इनकी तलाश करें:

• JSON आउटपुट में warnings[].code और primaryTargetId।
• क्या चेतावनी SSH फ़ॉलबैक, एकाधिक Gateway, अनुपलब्ध स्कोप या अनसुलझे प्रमाणीकरण संदर्भों के बारे में है।

सामान्य संकेत:

• SSH tunnel failed to start; falling back to direct probes. → SSH सेटअप विफल हुआ, लेकिन कमांड ने फिर भी सीधे कॉन्फ़िगर किए गए/लूपबैक लक्ष्यों को आज़माया।
• multiple reachable gateway identities detected → अलग-अलग Gateway ने उत्तर दिया, या OpenClaw यह प्रमाणित नहीं कर सका कि पहुँच योग्य लक्ष्य एक ही Gateway हैं। एक ही Gateway के लिए SSH टनल, प्रॉक्सी URL या कॉन्फ़िगर किए गए रिमोट URL को अनेक ट्रांसपोर्ट वाला एक Gateway माना जाता है, भले ही ट्रांसपोर्ट पोर्ट अलग हों।
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → कनेक्शन सफल रहा, लेकिन विस्तृत RPC स्कोप-सीमित है; डिवाइस पहचान को पेयर करें या operator.read वाले क्रेडेंशियल उपयोग करें।
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → कनेक्शन सफल रहा, लेकिन पूरा नैदानिक RPC सेट टाइम आउट हुआ या विफल रहा। इसे खराब नैदानिकी वाला पहुँच योग्य Gateway मानें; --json आउटपुट में connect.ok और connect.rpcOk की तुलना करें।
• Capability: pairing-pending या gateway closed (1008): pairing required → Gateway ने उत्तर दिया, लेकिन सामान्य ऑपरेटर पहुँच से पहले इस क्लाइंट को अभी भी पेयरिंग/स्वीकृति चाहिए।
• अनसुलझे gateway.auth.* / gateway.remote.* SecretRef चेतावनी टेक्स्ट → विफल लक्ष्य के लिए इस कमांड पथ में प्रमाणीकरण सामग्री उपलब्ध नहीं थी।

संबंधित:

• Gateway
• एक ही होस्ट पर एकाधिक Gateway
• रिमोट पहुँच

चैनल कनेक्ट है, संदेश प्रवाहित नहीं हो रहे

यदि चैनल की स्थिति कनेक्टेड है लेकिन संदेश प्रवाह बंद है, तो नीति, अनुमतियों और चैनल-विशिष्ट डिलीवरी नियमों पर ध्यान दें।

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

इनकी तलाश करें:

• DM नीति (pairing, allowlist, open, disabled)।
• समूह अनुमतिसूची और उल्लेख आवश्यकताएँ।
• अनुपलब्ध चैनल API अनुमतियाँ/स्कोप।

सामान्य संकेत:

• mention required → समूह उल्लेख नीति ने संदेश को अनदेखा किया।
• pairing / लंबित स्वीकृति ट्रेस → प्रेषक स्वीकृत नहीं है।
• missing_scope, not_in_channel, Forbidden, 401/403 → चैनल प्रमाणीकरण/अनुमतियों की समस्या।

संबंधित:

• चैनल समस्या निवारण
• Discord
• Telegram
• WhatsApp

Cron और Heartbeat डिलीवरी

यदि Cron या Heartbeat नहीं चला अथवा डिलीवर नहीं हुआ, तो पहले शेड्यूलर की स्थिति और फिर डिलीवरी लक्ष्य सत्यापित करें।

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw logs --follow

इनकी तलाश करें:

• Cron सक्षम हो और अगला वेक मौजूद हो।
• जॉब रन इतिहास की स्थिति (ok, skipped, error)।
• Heartbeat छोड़ने के कारण (quiet-hours, requests-in-flight, cron-in-progress, lanes-busy, alerts-disabled, empty-heartbeat-file, no-tasks-due)।

संबंधित:

• Heartbeat
• निर्धारित कार्य
• निर्धारित कार्य: समस्या निवारण

Node पेयर है, टूल विफल होता है

यदि कोई Node पेयर है लेकिन टूल विफल होते हैं, तो फ़ोरग्राउंड, अनुमति और स्वीकृति की स्थिति को अलग-अलग जाँचें।

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

इनकी तलाश करें:

• अपेक्षित क्षमताओं के साथ Node ऑनलाइन हो।
• कैमरा/माइक/स्थान/स्क्रीन के लिए OS अनुमति अनुदान।
• Exec स्वीकृतियाँ और अनुमतिसूची की स्थिति।

सामान्य संकेत:

• NODE_BACKGROUND_UNAVAILABLE → Node ऐप फ़ोरग्राउंड में होना चाहिए।
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → OS अनुमति अनुपलब्ध है।
• SYSTEM_RUN_DENIED: approval required → Exec स्वीकृति लंबित है।
• SYSTEM_RUN_DENIED: allowlist miss → कमांड को अनुमतिसूची ने अवरुद्ध किया।

संबंधित:

• Exec स्वीकृतियाँ
• Node समस्या निवारण
• Nodes

ब्राउज़र टूल विफल होता है

इसका उपयोग तब करें जब Gateway स्वयं स्वस्थ होने के बावजूद ब्राउज़र टूल की कार्रवाइयाँ विफल हों।

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

इनकी तलाश करें:

• क्या plugins.allow सेट है और उसमें browser शामिल है।
• मान्य ब्राउज़र निष्पादन योग्य पथ।
• CDP प्रोफ़ाइल की पहुँच-योग्यता।
• existing-session / user प्रोफ़ाइलों के लिए स्थानीय Chrome की उपलब्धता।

संबंधित:

• ब्राउज़र (OpenClaw-प्रबंधित)
• ब्राउज़र समस्या निवारण

यदि आपने अपग्रेड किया और अचानक कुछ खराब हो गया

अपग्रेड के बाद होने वाली अधिकांश खराबी कॉन्फ़िग विचलन या अब लागू किए जा रहे अधिक सख्त डिफ़ॉल्ट के कारण होती है।

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

यदि जाँच के बाद भी सेवा कॉन्फ़िगरेशन और रनटाइम में अंतर हो, तो उसी प्रोफ़ाइल/स्थिति डायरेक्टरी से सेवा मेटाडेटा फिर से इंस्टॉल करें:

openclaw gateway install --forceopenclaw gateway restart

संबंधित:

• प्रमाणीकरण
• बैकग्राउंड निष्पादन और प्रोसेस टूल
• Node पेयरिंग

संबंधित

• Doctor
• अक्सर पूछे जाने वाले प्रश्न
• Gateway रनबुक