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

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

कमांड क्रम

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

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 क्लाइंट, जहाँ OS अनुमति देता है वहाँ PID और कमांड लाइन सहित।
• ऐसी क्लाइंट प्रक्रिया जिसकी कमांड लाइन उस नए OpenClaw इंस्टॉलेशन या रैपर की ओर संकेत करती है जिससे आपने रोलबैक किया था।

समाधान:

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

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

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

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

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

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

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

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

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

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

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

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

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

संबंधित:

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

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

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

क्या करें:

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

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

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

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

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

   # 5-मिनट के cron या LaunchAgent के लिए उपयुक्त, launchd-संगत लाइवनेस जाँच का उदाहरण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 प्लेटफ़ॉर्म नोट्स
• लॉगिंग
• डॉक्टर

डुप्लिकेट 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/ के अंतर्गत जनरेट की गई फ़ाइल को संपादित न करें, क्योंकि सेवा पुनः इंस्टॉल करने, अपडेट करने और डॉक्टर द्वारा सुधार करने पर वह फ़ाइल फिर से जनरेट होती है:

   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 से इसका निरीक्षण करें।
• Gateway लॉग में memory pressure: level=critical दिखाई देता है → 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 बॉडी, क्रेडेंशियल, टोकन, कुकी या अपरिष्कृत सत्र ID नहीं। अपरिष्कृत लॉग कॉपी करने के बजाय बग रिपोर्ट के साथ डायग्नोस्टिक्स एक्सपोर्ट संलग्न करें।

संबंधित:

• 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)।

संबंधित:

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

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

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

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

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

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

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

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

संबंधित:

• निष्पादन अनुमोदन
• 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 रनबुक