इंस्टॉल और स्टार्ट न होने पर क्या करें: इंस्टॉलेशन और स्टार्टअप ट्रबलशूटिंग
OpenClaw इंस्टॉल नहीं हो रहा, चल नहीं रहा — अधिकांशतः तीन जगह अटकता है: Node एनवायरनमेंट मानक से कम, CLI PATH में नहीं, Gateway कॉन्फ़िगरेशन शुरू नहीं होता। यह पेज आधिकारिक ट्रबलशूटिंग दस्तावेज़ की सामान्य त्रुटियों को «त्रुटि के मूल पाठ» के अनुसार एक-एक करके कारण और समाधान देता है — पहले 60 सेकंड की त्वरित जांच, फिर मिलते-जुलते केस ढूंढें। त्रुटियों के मूल पाठ पूरी तरह आधिकारिक दस्तावेज़ और CLI डायग्नोस्टिक आउटपुट से लिए गए हैं, v2026.10.9 पर आधारित।
सीखने के बाद आप क्या कर सकेंगे
- 5 आधिकारिक डायग्नोस्टिक कमांड से 60 सेकंड में पहचानें: एनवायरनमेंट, CLI, Gateway, कॉन्फ़िगरेशन में से किस परत में समस्या है
- 21 सामान्य त्रुटियों को मिलते-जुलते केस से सुलझाएं: त्रुटि का मूल पाठ → कारण → सुधार कमांड
- चार परतों की ट्रबलशूटिंग सीमा पहचानें: एनवायरनमेंट → Gateway प्रक्रिया → कॉन्फ़िगरेशन और प्रमाणीकरण → क्लाइंट कनेक्शन
- अपडेट विफल होने पर पहले कौन से तीन कमांड चलाकर रिकवरी करें, और मदद कहां लें
openclaw doctorऔरopenclaw triageदो आधिकारिक टूल से हेल्थ-चेक और मास्क्ड डायग्नोसिस करें
आपकी मौजूदा दिक्कत
- npm से इंस्टॉल पूरा हुआ,
openclawटाइप करते हीcommand not found;sudoसे इंस्टॉल किया तो फिर अनुमति त्रुटि - Gateway किसी तरह इंस्टॉल हुआ,
openclaw gateway statusसे देखा तो stopped, लॉग में अनजानी त्रुटियों की झड़ी - अपडेट के बाद उल्टा शुरू नहीं हो रहा: चैनल खाली, मॉडल कॉल 401, समझ नहीं आ रहा अपडेट खराब हुआ या अपनी कॉन्फ़िगरेशन
यह तरीका कब उपयोग करें
जब आपको चाहिए:
- अटकी हुई त्रुटियां ठीक करें इंस्टॉलेशन: 5 मिनट में चालू हो जाए या इंस्टॉल के वैकल्पिक तरीके में
- Gateway सेवा के रूप में इंस्टॉल होने के बाद शुरू न होने, Control UI कनेक्ट न होने की समस्या ठीक करना
- एक विफल अपडेट से रिकवर होना
और आप नहीं चाहते:
- त्रुटि मिलते ही फोरम पर पोस्ट करके इंतज़ार करना — 60 सेकंड की त्वरित जांच अधिकांश इंतज़ार बचा सकती है
- «एनवायरनमेंट खराब» और «कॉन्फ़िगरेशन खराब» में फर्क न पहचानकर दोनों तरफ बेतरतीब बदलाव करना
🎒 शुरू करने से पहले की तैयारी
- इंस्टॉल मुख्य पथ या वैकल्पिक इंस्टॉल तरीके से गुज़रे हों — किसी भी कदम पर अटके हों कोई बात नहीं, यह पेज अटकन हिलाने के लिए ही है
- टर्मिनल में कमांड चल सकती हों: macOS / Linux / WSL2 पर Bash, Windows पर PowerShell
- त्रुटि का मूल पाठ पूरा कॉपी करने की आदत हो — यह पेज त्रुटि के मूल पाठ के अनुसार वर्गीकृत है, शब्दशः मिलान से ही केस मिलेगा
मूल विचार
पहले परत पहचानें, फिर त्रुटि देखें। कमांड टाइप करने से AI उत्तर पाने तक चार परतें आती हैं, हर परत की त्रुटियां अलग दिखती हैं:
| परत | क्या होता है | त्वरित जांच | विशिष्ट त्रुटियां |
|---|---|---|---|
| 1. एनवायरनमेंट | Node बहुत पुराना या इंस्टॉल नहीं; CLI PATH में नहीं | node -v / openclaw --version | command not found,node:sqlite truncates TEXT |
| 2. Gateway प्रक्रिया | शुरू नहीं होता, पोर्ट व्यस्त, इंस्टॉल हुई सेवा नहीं चलती | openclaw gateway status | EADDRINUSE,Gateway start blocked |
| 3. कॉन्फ़िगरेशन और प्रमाणीकरण | कॉन्फ़िगरेशन गलत लिखा गया, token गलत | openclaw doctor | Invalid config at ..., AUTH_TOKEN_MISSING |
| 4. क्लाइंट कनेक्शन | Control UI कनेक्ट नहीं हो पा रहा | curl http://127.0.0.1:18789 | gateway connect failed: |
दो आधिकारिक डायग्नोस्टिक टूल सबसे आसान हैं। openclaw doctor सामान्य कॉन्फ़िगरेशन/सेवा समस्याओं की जाँच कर ठीक करता है; openclaw triage संवेदनशील जानकारी हटाई हुई (secrets, token, मूल चैट सामग्री, मूल लॉग किसी भी में शामिल नहीं) एक डायग्नोस्टिक रिपोर्ट बनाता है, जिसे आप सीधे अपनी मशीन पर मौजूद कोडिंग agent को आगे काम जारी रखने के लिए दे सकते हैं; पुष्टि प्रॉम्प्ट आने पर 30 सेकंड के भीतर Yes का उत्तर न दें, तो स्टार्टअप छोड़कर केवल वह मैनुअल कमांड प्रिंट होगा।
💡 चीन का नेटवर्क
आधिकारिक दस्तावेज़ npm मिरर या डाउनलोड त्वरण समाधान प्रदान नहीं करता, इसलिए यह लेख मिरर पते का अनुमान नहीं लगाता। इंस्टॉल स्क्रिप्ट या डिपेंडेंसी डाउनलोड करते समय टाइमआउट हो, तो पहले नेटवर्क वातावरण जाँचें और फिर पुनः प्रयास करें; अज्ञात स्रोत वाली «चीनी मिरर» स्क्रिप्ट पर भरोसा न करें।
पहली जाँच: 60 सेकंड की त्वरित जाँच
पाँच कमांड क्रम से चलाएँ, बारी-बारी से Node, CLI, Gateway, कॉन्फ़िगरेशन की पुष्टि करें; जो कड़ी टूटी हो वहीं से ठीक करें।
# 1. Node 在支持范围吗?——要 24.16.0+(24.x)或 26.1.0+,建议 24.22.1+/26.12.1+
node -v
# 2. CLI 装上了吗?——应打印版本号(本页基准 v2026.10.9)
openclaw --version
# 3. Gateway 起来了吗?——应看到 Runtime: running、监听 18789
openclaw gateway status
# 4. 配置/服务有内伤吗?——应无 blocking 错误
openclaw doctor
# 5. 还是一头雾水?——一键生成脱敏诊断
openclaw triageआपको यह दिखना चाहिए: कमांड 1 v24.16.0+ या v26.1.0+ प्रिंट करे; कमांड 2 वर्ज़न नंबर प्रिंट करे; कमांड 3 Runtime: running; कमांड 4 बिना अवरोधक त्रुटि। जो कड़ी टूटी हो, नीचे उसके संगत समूह पर जाएँ।
सामान्य समस्याओं की जाँच
इंस्टॉलेशन और वातावरण: इंस्टॉल नहीं हो रहा
"openclaw: command not found"
कारण: आधिकारिक दस्तावेज़ के मूल शब्द «लगभग हमेशा PATH की समस्या होती है» — npm का ग्लोबल bin निर्देशिका आपके shell के PATH में नहीं है। nvm / fnm जैसे वर्ज़न मैनेजर का उपयोग करते हैं पर उसे shell स्टार्टअप फ़ाइल में नहीं लिखा, तो वहीं भी फँसेंगे। Windows पर इसका रूपांतर openclaw is not recognized है।
समाधान:
- तीन पंक्तियों में पता लगाएँ:
node -v # Node 装了吗
npm prefix -g # 全局包装在哪
echo "$PATH" # 全局 bin 目录在 PATH 里吗- macOS / Linux: ग्लोबल bin को PATH में जोड़ें, shell स्टार्टअप फ़ाइल में लिखें (zsh के लिए
${ZDOTDIR:-$HOME}/.zshrc, bash के लिए~/.bashrc):
export PATH="$(npm prefix -g)/bin:$PATH"फिर नया टर्मिनल खोलें, या zsh में rehash, bash में hash -r।
- Windows:
npm config get prefixकी आउटपुट निर्देशिका (अधिकांश सिस्टम पर%AppData%\npm,\binसफ़िक्स जोड़ने की ज़रूरत नहीं) को यूज़र PATH में जोड़ें, PowerShell दोबारा खोलें।
आपको यह दिखना चाहिए: नए टर्मिनल में openclaw --version वर्ज़न नंबर प्रिंट करे।
"npm error spawn git / git not found"
कारण: Windows इंस्टॉलर git इंस्टॉल मार्ग पर चलते समय Git नहीं ढूँढ पाता — Git for Windows इंस्टॉल नहीं है, या इंस्टॉल है पर PATH में नहीं है।
समाधान: Git for Windows इंस्टॉल करें (आधिकारिक FAQ की सलाह), पुष्टि करें कि git PATH में है → PowerShell पूरी तरह बंद कर दोबारा खोलें → इंस्टॉलर दोबारा चलाएँ।
"EACCES" (npm install -g अनुमति अस्वीकृत)
कारण: Linux पर ग्लोबल npm निर्देशिका root की है, वर्तमान यूज़र उसमें लिख नहीं सकता।
समाधान: npm का ग्लोबल prefix यूज़र-लिखने योग्य निर्देशिका में बदलें:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"export PATH=... वाली पंक्ति ~/.bashrc या ${ZDOTDIR:-$HOME}/.zshrc में लिखें, फिर OpenClaw दोबारा इंस्टॉल करें।
"blocked because they are not covered by allowScripts"
कारण: npm 12 डिफ़ॉल्ट रूप से अस्वीकृत पैकेज लाइफ़साइकल स्क्रिप्ट रोकता है, OpenClaw के preinstall / postinstall रोक दिए जाते हैं। npm 11.16 केवल चेतावनी देता है पर फिर भी चलने देता है; npm 11.15 और उससे पहले के संस्करणों में यह नीति नहीं है। सावधान रहें: npm 11.16 द्वारा सुझाया गया npm approve-scripts openclaw ग्लोबल इंस्टॉल परलागू नहीं होता — ENOMATCH No installed packages match: openclaw त्रुटि देगा।
समाधान: इंस्टॉल करते समय सही पैरामीटर दें:
# npm 12 或 11.16+
npm install -g openclaw@latest --allow-scripts=openclaw
# npm 11.15 及更早:同命令去掉 --allow-scripts=openclawNode <v>: node:sqlite truncates TEXT at embedded NUL (nodejs/node#61954); use 24.16+/26.1+ or a build with the fix
कारण: OpenClaw की कठोर शर्तें: Node 24.16.0+ (24.x) या 26.1.0+ (engines एक्सप्रेशन >=24.16.0 <25 || >=26.1.0), और लोड होने वाली SQLite लाइब्रेरी WAL सुरक्षा जाँच पास करे (SQLite 3.51.3+, या 3.50.x में ≥ 3.50.7, 3.44.x में ≥ 3.44.6)। Node 22, 23, 25 किसी का भी समर्थन नहीं; आधिकारिक रूप से दृढ़ता से 24.22.1+ / 26.12.1+ की सलाह है (सुरक्षा सुधार)।
समाधान:
node -vसे वर्ज़न देखें, बहुत पुराना हो तो अपग्रेड करें (Node 26 अनुशंसित वर्ज़न है)। इंटरैक्टिव टर्मिनल में CLIUpdate NodeJS: Y/N [N]:प्रॉम्प्ट दिखाएगा — Y दबाएँ ताकि वह एक सत्यापित निजी रनटाइम~/.openclaw/tools/cli-nodeमें डाउनलोड करे, सिस्टम Node को न छुए।- आधिकारिक इंस्टॉलर Node के न होने पर स्वतः जोड़ देता है: macOS पर Node 26, Linux पर Node 24 LTS इंस्टॉल करता है।
- प्लेटफ़ॉर्म सीमाएँ: आधिकारिक Node 24+ के macOS बाइनरी macOS 13.5+ के अनुसार बने हैं, 11–13.4 परीक्षित नहीं, समर्थित नहीं; Linux ARMv7 का आधिकारिक बिल्ड नहीं है, 64-बिट सिस्टम आवश्यक है।
- RPM-आधारित डिस्ट्रिब्यूशन (Fedora / RHEL): डिस्ट्रिब्यूशन का Node असुरक्षित सिस्टम SQLite से जुड़ा होता है, आधिकारिक इंस्टॉलर स्वतः यूज़र-मोड रनटाइम का उपयोग कर लेता है, आपको कुछ करने की ज़रूरत नहीं।
आपको यह दिखना चाहिए: node -v v24.16.0+ या v26.1.0+ प्रिंट करे, त्रुटि गायब हो जाए। आधिकारिक रूप से यह भी याद दिलाया गया है: पहले Node अपग्रेड करें फिर OpenClaw अपडेट करें, ताकि SQLite TEXT कटौती से बचें।
"blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)"
कारण: Docker इमेज node यूज़र (uid 1000) से चलता है, होस्ट मशीन पर माउंट की गई निर्देशिका का स्वामी मेल नहीं खाता, प्लगइन सुरक्षा नीति से रुक जाता है, और अक्सर बाद में plugin present but blocked संदेश आता है।
समाधान: माउंट की गई निर्देशिका का स्वामी 1000 बना दें:
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fixकेवल तभी /path/to/openclaw-config/npm को root:root में बदलें जब आप OpenClaw को लंबे समय तक root के रूप में चला रहे हों। Docker डिप्लॉयमेंट विवरण सर्वर डिप्लॉयमेंट में देखें।
💡 इंस्टॉलर अटक गया, कोई प्रतिक्रिया नहीं?
दोबारा चलाएँ और --verbose जोड़ें:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verboseinstall.ps1 का कोई संगत स्विच नहीं है, इसे Set-PSDebug -Trace 1 / -Trace 0 से एक लेयर में रैप करें।
Gateway: शुरू नहीं हो रहा
पहले openclaw gateway status चलाएँ (--deep जोड़ने पर सिस्टम-स्तरीय सेवाएँ भी स्कैन होती हैं) और openclaw logs --follow से लॉग देखें, फिर नीचे दी गई त्रुटियों से मिलान करें।
"Gateway start blocked: set gateway.mode=local"
कारण: कॉन्फ़िगरेशन में gateway.mode का लोकल-मोड मार्कर गायब है — लोकल मोड सक्षम नहीं है, या कॉन्फ़िगरेशन फ़ाइल खराब होने से फ़ील्ड खो गई है (लॉग में existing config is missing gateway.mode भी लिखा हो सकता है)। Podman परिनियोजन में ध्यान दें कि डिफ़ॉल्ट कॉन्फ़िगरेशन पथ ~/.openclaw/openclaw.json है।
समाधान (दो आधिकारिक सुधार):
- कॉन्फ़िगरेशन में
gateway.mode="local"सेट करें; - या
openclaw onboard --mode local/openclaw setupदोबारा चलाएँ, जिससे लोकल-मोड कॉन्फ़िगरेशन की एक नई प्रति बन जाए।
"another gateway instance is already listening" / EADDRINUSE
कारण: डिफ़ॉल्ट पोर्ट 18789 व्यस्त है — आमतौर पर डुप्लिकेट Gateway सेवाएँ इंस्टॉल हो गई हैं, या किसी अन्य प्रोसेस ने पोर्ट घेर लिया है।
समाधान:
openclaw gateway status --deepसे डुप्लिकेट launchd / systemd / शेड्यूल्ड टास्क सेवाएँ स्कैन करें,Other gateway-like services detected (best effort)के क्लीनअप संकेत पर ध्यान दें।- आधिकारिक सलाह है कि अधिकांश इंस्टॉलेशन में एक मशीन पर एक ही Gateway रखें; वाकई कई चलाने हों तो पोर्ट + कॉन्फ़िगरेशन + स्टेट + वर्कस्पेस अलग-अलग रखना अनिवार्य है।
- macOS विशेष स्थिति:
ai.openclaw.gatewayऔरai.openclaw.nodeदोनों LaunchAgent एक साथ सक्रिय होने परEADDRINUSE/respawn का तेज़ लूप बन जाता है — node सुविधा की ज़रूरत न हो तोopenclaw node uninstallकर दें। - क्लीनअप के बाद
openclaw gateway restart, status मेंRuntime: runningदिखना चाहिए।
"refusing to bind gateway ... without auth"
कारण: Gateway डिफ़ॉल्ट रूप से केवल लोकल लूपबैक पते (loopback) + पोर्ट 18789 पर सुनता है। आप गैर-loopback पता बाँधना चाहते हैं पर प्रमाणीकरण कॉन्फ़िगर नहीं किया — OpenClaw शुरू होने से इनकार करता है (fail closed, यह जानबूझकर की गई सुरक्षा डिज़ाइन है)।
समाधान: दो में से एक चुनें:
- लूपबैक पर ही सुनते रहें, रिमोट एक्सेस के लिए SSH टनल (
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host) या Tailscale इस्तेमाल करें; - Gateway के लिए प्रमाणीकरण कॉन्फ़िगर करें (token / password, या trusted-proxy), नियमों के लिए देखें सुरक्षा सख्त करना (भाग 1)। अभी तक shared secret कॉन्फ़िगर नहीं किया है?
openclaw doctor --generate-gateway-tokenसे एक जनरेट करें।
"Invalid config at ..."
कारण: कॉन्फ़िगरेशन फ़ाइल सत्यापन में नहीं उतरी — हाथ से खराब संपादन, गलत संरचना, या अपरिचित कीज़ घुस गईं। Gateway शुरू होने से इनकार करता है; चलता हुआ Gateway भी हॉट-रीलोड में खराब संपादन छोड़ देता है (लॉग में config reload skipped (invalid config): ... लिखता है)।
समाधान:
- पता लगाएँ और सत्यापित करें:
openclaw config file # 配置文件在哪
openclaw config validate # 哪一条不过- doctor से ठीक करवाएँ:
openclaw doctor --fixखराब हुई कॉन्फ़िगरेशन ठीक कर सकता है या last-known-good बहाल कर सकता है; अस्वीकृत खराब सामग्री पास में.rejected.*/.clobbered.*फ़ाइलों में रखी जाती है (.clobbered.*हर कॉन्फ़िगरेशन पथ के लिए नवीनतम 32 प्रतियाँ), केवल बदले हुए कीज़ वापस लेने हों तो वहाँ से कॉपी करें। - हाथ से ठीक करें तो: पूरी JSON5 संरचना बनाए रखें, केवल लक्षित की बदलें, बदलने के बाद
openclaw config validateसे पास कराकर पुनः शुरू करें।
"Gateway service port does not match current gateway config"
कारण: इंस्टॉल हुई बैकग्राउंड सेवा अभी भी पुराने --port से बंधी है — आमतौर पर पोर्ट कॉन्फ़िगरेशन बदलने के बाद होता है।
समाधान:
openclaw doctor --fix # 或 openclaw gateway install --force
openclaw gateway restartControl UI: कनेक्ट नहीं हो रहा
Gateway जीवित है पर ब्राउज़र कनेक्ट नहीं हो पा रहा? इस समूह की त्रुटियाँ सब «क्लाइंट → Gateway» के आख़िरी हिस्से में आती हैं।
"gateway connect failed:"
कारण: Control UI जिस URL / पोर्ट की ओर इशारा करता है वह गलत है, या Gateway अभी चल ही नहीं रहा।
समाधान: लोकल मशीन पर तीन-चरणीय सत्यापन:
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789curl से OpenClaw का HTML वापस पाएँ → Gateway ठीक है, समस्या ब्राउज़र पक्ष में है: सीधे http://127.0.0.1:18789 खोलें, कैश साफ़ करें, पुराने डीपलिंक इस्तेमाल न करें। restart के बाद भी सेवा न उठे तो openclaw gateway start करें और फिर openclaw gateway status से जाँचें।
"AUTH_TOKEN_MISSING"
कारण: Gateway में token / password प्रमाणीकरण कॉन्फ़िगर है, पर क्लाइंट shared token साथ नहीं भेज रहा।
समाधान:
- Gateway होस्ट के इंटरैक्टिव टर्मिनल से token लें:
openclaw gateway auth-token --show- आउटपुट को Control UI सेटिंग्स में पेस्ट करके दोबारा कोशिश करें। अभी तक token कॉन्फ़िगर नहीं किया?
openclaw doctor --generate-gateway-tokenसे जनरेट करें; token का स्रोतgateway.auth.token(या एनवायरनमेंट वेरिएबलOPENCLAW_GATEWAY_TOKEN) है। - अब भी कनेक्ट न हो, तो आधिकारिक auth त्रुटि-कोड तालिका से मिलान करें:
| त्रुटि कोड | अर्थ | अगला कदम |
|---|---|---|
AUTH_TOKEN_MISMATCH | shared token मेल नहीं खाता | एक बार डिवाइस token को भरोसेमंद पुनःप्रयास की अनुमति; फिर भी विफल रहे तो आधिकारिक token-ड्रिफ़्ट चेकलिस्ट अपनाएँ |
AUTH_DEVICE_TOKEN_MISMATCH | डिवाइस token बहुत पुराना है या रद्द कर दिया गया है | devices CLI से रोटेट/पुनः स्वीकृत करें |
AUTH_SCOPE_MISMATCH | डिवाइस token के पर्याप्त अधिकार नहीं | फिर से पेयर करें या माँगे गए scope को स्वीकृत करें, shared token घुमाने न जाएँ |
PAIRING_REQUIRED | डिवाइस पहचान स्वीकृति की प्रतीक्षा में | openclaw devices approve <requestId> |
"device identity required" और "origin not allowed"
कारण: पहला — क्लाइंट ने डिवाइस पहचान नहीं भेजी (token / password मोड में भी इसे छोड़ा नहीं जा सकता, shared secret इसका विकल्प नहीं); दूसरा — ब्राउज़र का Origin श्वेतसूची में नहीं है, सार्वजनिक नेटवर्क या क्रॉस-ओरिजिन परिनियोजन पर gateway.controlUi.allowedOrigins में प्रविष्टि जोड़नी होगी (निजी LAN और Tailscale पतों को श्वेतसूची की ज़रूरत नहीं)।
समाधान: पहले के लिए डिवाइस पेयरिंग दोबारा पूरी करें; दूसरे के लिए परिनियोजन का Origin gateway.controlUi.allowedOrigins में जोड़कर पुनः कनेक्ट करें।
"too many failed authentication attempts (retry later)"
कारण: एक ही ब्राउज़र Origin से बार-बार प्रमाणीकरण विफल होने पर अस्थायी लॉकआउट हो गया। अन्य localhost origin के अलग काउंटर बकेट हैं, वे प्रभावित नहीं होते।
समाधान: कोशिशें रोकें और लॉक पर प्रहार करते न रहें; पहले AUTH_TOKEN_MISSING वाली पंक्ति से पुष्टि करें कि क्रेडेंशियल सही हैं, फिर थोड़ी देर बाद पुनः प्रयास करें।
"Wake up, my friend!" पर अटका है, कोई जवाब नहीं
कारण: onboarding का incubation स्क्रीन Gateway के reachable और authenticated होने पर निर्भर करता है। अगर model / auth सेटअप छोड़ दिया गया हो, तो wizard Model auth missing दिखाकर सीधे TUI खोल देता है, कोई संदेश नहीं भेजता; अगर wake phrase दिखता है पर tokens 0 पर रुके रहते हैं, तो इसका मतलब है कि agent चला ही नहीं।
समाधान:
openclaw gateway restart
openclaw status
openclaw models status
openclaw logs --followफिर भी न हो तो openclaw doctor। अगर model provider या credentials सही से configure नहीं हुए हैं, तो openclaw onboard चलाकर दोबारा configure करें—यह "model provider और authentication बदलने" का आधिकारिक रूप से निर्दिष्ट एकमात्र command है।
Update fail होना
Update failure के recovery के entry points तीन निश्चित हैं: openclaw update status --json (recorded failed step और reason code देखने के लिए), openclaw triage (sanitized diagnostics), openclaw doctor --fix। Control UI के Settings → Updates में सबसे हालिया attempt का समय, पहले-बाद के versions, failed step और reason code दिखते हैं।
"managed-service-handoff-failed"
कारण: जब console का log level debug होता है, तो affected versions का update handoff reject हो जाता है। Affected stable versions: 2026.9.6–2026.9.9 और 2026.10.1–2026.10.5।
समाधान: logging.consoleLevel को "info" सेट करें, Gateway और update command के environment से OPENCLAW_LOG_LEVEL=debug हटा दें (file logging debug पर रह सकती है), openclaw update चलाएँ, और पूरा होने पर original log settings वापस लाएँ।
"global-install-permission-denied"
कारण: global npm prefix writable नहीं है—यह आमतौर पर Homebrew के Node, system prefix, या version manager switch करने के बाद किसी दूसरे prefix की ओर point करने के कारण होता है।
समाधान: error में नाम लिए गए directory और owner की जाँच करें:
- Directory आपकी है → error में दी गई
chmod u+rwxcommand से ठीक करें; - Directory administrator की है → किसी authorized account से update चलवाएँ, या आपको authorization दिलवाएँ;
- Personal install के लिए user-writable prefix पर switch कर सकते हैं (ऊपर EACCES वाला तरीका देखें)।
⚠️ पूरे updater को sudo से मत चलाएँ
आधिकारिक रूप से स्पष्ट चेतावनी है: पूरे updater को sudo से चलाने पर एक अलग home और service account चुना जा सकता है। Shared system prefix के owner को recursively बदलना भी न करें।
"ETARGET" / "E404" / "EINTEGRITY"
कारण: npm package resolve या download करने में fail हुआ—target version registry पर नहीं मिला, cache stale है, या registry / mirror configuration में समस्या है।
समाधान:
npm cache verify
npm view <spec> version # 用报错里给出的 spec 验证अपने configured registry या mirror की जाँच करके दोबारा try करें। Current updater named dependency failure पर एक बार automatically retry करता है (npm के लिए --prefer-online, Bun के लिए --no-cache)।
"protocol mismatch" (rollback के बाद लगातार repeat होता है)
कारण: पुराने Gateway पर rollback करने के बाद भी कुछ नए client processes पुराने Gateway की समझ से बाहर protocol ranges के साथ reconnect कर रहे हैं। Logs का रूप protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> जैसा होता है।
समाधान:
openclaw gateway status --deep(याopenclaw doctor --deep) से stale client PID ढूँढकर उसे बंद करें;- जिन चीज़ों में OpenClaw embedded है उन्हें restart करें: local dashboard, editor, app-server helper,
openclaw logs --followलगाए long-running shell; - फिर
--deepएक बार चलाकर confirm करें कि पुराना PID गायब हो गया है। पुराने Gateway को नया protocol ज़बरदस्ती accept मत कराएँ—protocol version communication contract की रक्षा करता है।
"plugin load failed: dependency tree corrupted; run openclaw doctor --fix"
कारण: update अभी-अभी पूरा हुआ है, channel list blank है या model call 401 error दे रहा है—दोनों ही update के finalization पूरा न होने की ओर point करते हैं: channel plugin registration fail हुआ (channel configuration अभी मौजूद है, plugin load नहीं हुआ); या provider 401 stale per-agent OAuth credentials की shadow से आ रहा है।
समाधान: update के बाद का सामान्य recovery पाँच-step क्रम:
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restartdoctor --fix stale OAuth shadows को साफ करता है और corrupted dependency tree ठीक करता है। आधिकारिक रूप से यह भी आगाह किया गया है: update fail होने के बादतुरंत state rollback मत करें—पहले current state रखते हुए known-good code reinstall करें, और सिर्फ़ तब update से पहले का backup restore करें जब पुराना code नई configuration/database पढ़ न पाए।
फिर भी नहीं होता?
पहले evidence इकट्ठा करें, फिर पूछें। आधिकारिक "I am stuck" guide की diagnostic commands table है, एक बार चलाकर output (sanitize करके) संलग्न करें:
| Command | क्या दिखता है |
|---|---|
openclaw status | Gateway / agent health + basic configuration snapshot |
openclaw status --all | पूरा read-only diagnostics, सीधे paste किया जा सकता है |
openclaw models status | provider authentication + model availability |
openclaw doctor | common configuration / state समस्याएँ validate और fix करता है |
openclaw logs --follow | real-time logs का tail |
openclaw gateway status --deep | Gateway / configuration / plugin की गहरी जाँच |
openclaw health --verbose | विस्तृत health report |
Update-संबंधी failures के लिए openclaw update status --json का output भी संलग्न करें। एक openclaw triage sanitized diagnostics generate कर देता है—भेजने से पहले एक बार जाँच लें, credentials, raw configuration या unsanitized process output संलग्न न करें।
कहाँ पूछें:
| Channel | किसके लिए सही |
|---|---|
| community.openclaw.ai | आधिकारिक support site: configuration, environment-संबंधी समस्याओं के लिए पहले यहीं आएँ |
| GitHub issue chooser | reproduce हो सकने वाले product defects / documentation bugs, reproduction steps और evidence के साथ |
| आधिकारिक troubleshooting documentation | symptom-first आधिकारिक troubleshooting entry point, इस page के कई errors का स्रोत |
Checkpoint ✅
- 60 सेकंड में पाँच commands चलाकर पता है कि किस layer पर अटके हैं
openclaw --versionversion number print कर पाता है,command not foundठीक हो चुका हैnode -v24.16.0+ (24.x) या 26.1.0+ range में हैopenclaw gateway statusRuntime: runningदिखाता है, 18789 पर listen कर रहा है- प्रश्न पूछते समय
openclaw status --allजैसा sanitized diagnostics output संलग्न करेंगे
अक्सर पूछे जाने वाले प्रश्न
OpenClaw का क्या मतलब है?
OpenClaw एक AI टूल है जो npm के ज़रिए इंस्टॉल होता है, और इसमें openclaw CLI, एक स्थायी Gateway सेवा और ब्राउज़र में Control UI शामिल हैं, जिसका उपयोग विभिन्न मॉडल provider से जुड़कर AI agent चलाने के लिए किया जाता है। यह पेज विशेष रूप से इसके इंस्टॉलेशन और स्टार्टअप चरण की त्रुटियों को संभालता है; अगर इंस्टॉल न हो या चल न पाए, तो पहले ऊपर दिया गया「60 सेकंड में तुरंत जाँच」देखें।
OpenClaw का उपयोग कैसे करें? कोई विस्तृत ट्यूटोरियल है?
शुरुआत इंस्टॉलेशन से होती है: पहले इंस्टॉलेशन:5 मिनट में चालू करें देखें, या इंस्टॉलेशन के वैकल्पिक तरीके चुनें। इंस्टॉल के बाद openclaw gateway status से Runtime: running की पुष्टि करें और 18789 पर सुनें, फिर openclaw onboard से मॉडल और प्रमाणीकरण कॉन्फ़िगरेशन पूरा करें, और फिर ब्राउज़र में http://127.0.0.1:18789 खोलकर Control UI का उपयोग करें।
इस पाठ का सारांश
✅ Troubleshooting में पहले layer तय करें: environment (Node / CLI) → Gateway process → configuration और authentication → client connection, हर layer के लिए निश्चित check commands हैं।
✅ OpenClaw इंस्टॉल न होने के तीन मुख्य स्रोतों (PATH, npm अनुमतियाँ, Node संस्करण) के लिए निश्चित समाधान हैं: PATH जोड़ें, यूज़र-लिखने-योग्य prefix सेट करें, और 24.16.0+/26.1.0+ पर अपग्रेड करें।
✅ दो आधिकारिक टूल याद रखें: openclaw doctor स्वास्थ्य-जाँच व मरम्मत के लिए, openclaw triage संवेदनशील जानकारी हटाई हुई डायग्नोस्टिक्स देता है जिसे सीधे कोडिंग agent को दिया जा सकता है।
✅ अपडेट विफल होने पर पहले रिकवरी प्रवेश-द्वार से शुरू करें: openclaw update status --json → openclaw triage → openclaw doctor --fix, जल्दबाज़ी में स्थिति रोलबैक न करें।
मुख्य एरर संदेशों की त्वरित सूची:
| एरर संकेत | स्तर | पहला कदम |
|---|---|---|
openclaw: command not found | परिवेश | npm prefix -g → PATH जोड़ें |
node:sqlite truncates TEXT ... | परिवेश | Node को 24.16+/26.1+ पर अपग्रेड करें |
blocked ... allowScripts | परिवेश | --allow-scripts=openclaw पुनः इंस्टॉल करें |
Gateway start blocked: set gateway.mode=local | Gateway | gateway.mode=local फिर से सेट करें |
EADDRINUSE | Gateway | status --deep डुप्लिकेट सर्विस खोजें |
Invalid config at ... | कॉन्फ़िगरेशन | doctor --fix + config validate |
AUTH_TOKEN_MISSING | प्रमाणीकरण | gateway auth-token --show |
managed-service-handoff-failed | अपडेट | consoleLevel को info सेट करें |
protocol mismatch | अपडेट | --deep पुराने क्लाइंट प्रोसेस खोजकर बंद करें |
कमांड और कॉन्फ़िगरेशन की पूरी त्वरित सूची के लिए CLI कमांड और कॉन्फ़िगरेशन क्विक रेफ़रेंस देखें।
अगले पाठ की झलक
परिवेश स्थिर हो गया और Gateway हमेशा चालू रहने लगा है, अब अगला कदम "दिमाग़" को जोड़ने का है। अगला पाठ: मॉडल कनेक्शन की समीक्षा: provider व्यवस्था और मॉडल स्विचिंग।
आप सीखेंगे:
provider/modelमॉडल संदर्भ कैसे पढ़ें, और आधिकारिक provider प्लगइन के लिए कॉन्फ़िगरेशन एंट्री क्यों लिखने की ज़रूरत नहीं हैopenclaw modelsकमांड परिवार: list / set / status- घरेलू मॉडलों की पूरी मैट्रिक्स: DeepSeek, Qianwen, GLM, Kimi, MiniMax, Doubao…… हर एक के लिए एक पृष्ठ