عیب‌یابی

این صفحه runbook عمیق است. اگر ابتدا جریان triage سریع را می‌خواهید، از /help/troubleshooting شروع کنید.

نردبان فرمان‌ها

ابتدا این‌ها را به همین ترتیب اجرا کنید:

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

نشانه‌های مورد انتظار برای وضعیت سالم:

• openclaw gateway status، Runtime: running، Connectivity probe: ok، و یک خط Capability: ... را نشان می‌دهد.
• openclaw doctor هیچ مشکل مسدودکننده‌ای در config/service گزارش نمی‌کند.
• openclaw channels status --probe وضعیت زنده transport برای هر حساب را نشان می‌دهد و، در موارد پشتیبانی‌شده، نتایج probe/audit مانند works یا audit ok را نمایش می‌دهد.

پس از یک به‌روزرسانی

وقتی به‌روزرسانی تمام شده اما Gateway پایین است، channelها خالی هستند، یا فراخوانی‌های مدل با خطاهای 401 شکست می‌خورند، از این بخش استفاده کنید.

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

دنبال این موارد بگردید:

• Update restart در openclaw status / openclaw status --all. handoffهای در انتظار یا شکست‌خورده فرمان بعدی برای اجرا را شامل می‌شوند.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix زیر Channels. این یعنی config مربوط به channel هنوز وجود دارد، اما ثبت Plugin پیش از آنکه channel بتواند بارگذاری شود شکست خورده است.
• خطاهای 401 provider پس از احراز هویت دوباره. openclaw doctor --fix وجود سایه‌های auth قدیمی OAuth برای هر agent را بررسی می‌کند و نسخه‌های قدیمی را حذف می‌کند تا همه agentها profile مشترک فعلی را resolve کنند.

نصب‌های split brain و نگهبان config جدیدتر

وقتی یک سرویس gateway پس از به‌روزرسانی به‌طور غیرمنتظره متوقف می‌شود، یا logها نشان می‌دهند که یک باینری openclaw قدیمی‌تر از نسخه‌ای است که آخرین بار openclaw.json را نوشته، از این بخش استفاده کنید.

OpenClaw نوشتن‌های config را با meta.lastTouchedVersion نشان‌گذاری می‌کند. فرمان‌های فقط‌خواندنی همچنان می‌توانند config نوشته‌شده توسط OpenClaw جدیدتر را بررسی کنند، اما mutationهای process و service از ادامه دادن با یک باینری قدیمی‌تر خودداری می‌کنند. اقدام‌های مسدودشده شامل شروع، توقف، restart، uninstall سرویس gateway، reinstall اجباری service، راه‌اندازی gateway در حالت service، و پاک‌سازی port با gateway --force هستند.

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

openclaw gateway install --forceopenclaw gateway restart

ناسازگاری protocol پس از rollback

وقتی پس از downgrade یا rollback کردن OpenClaw، logها همچنان protocol mismatch چاپ می‌کنند، از این بخش استفاده کنید. این یعنی یک Gateway قدیمی‌تر در حال اجراست، اما یک process کلاینت محلی جدیدتر هنوز تلاش می‌کند با بازه protocolی reconnect کند که Gateway قدیمی‌تر نمی‌تواند صحبت کند.

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

دنبال این موارد بگردید:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> در logهای Gateway.
• Established clients: در openclaw gateway status --deep یا Gateway clients در openclaw doctor --deep. این فهرست کلاینت‌های TCP فعال متصل به port Gateway را نشان می‌دهد، از جمله PIDها و command lineها وقتی OS اجازه دهد.
• یک process کلاینت که command line آن به نصب یا wrapper جدیدتر OpenClaw اشاره می‌کند که از آن rollback کرده‌اید.

رفع:

1. process کلاینت قدیمی OpenClaw را که gateway status --deep نشان می‌دهد متوقف یا restart کنید.
2. appها یا wrapperهایی را که OpenClaw را embed می‌کنند restart کنید، مانند داشبوردهای محلی، ویرایشگرها، helperهای app-server، یا shellهای بلندمدت openclaw logs --follow.
3. openclaw gateway status --deep یا openclaw doctor --deep را دوباره اجرا کنید و تأیید کنید PID کلاینت قدیمی حذف شده است.

یک Gateway قدیمی‌تر را وادار نکنید protocol جدیدتر ناسازگار را بپذیرد. افزایش‌های protocol از قرارداد wire محافظت می‌کنند؛ بازیابی rollback مسئله پاک‌سازی process/version است.

Symlink مربوط به Skill به‌عنوان خروج از path نادیده گرفته شد

وقتی logها شامل این مورد هستند از این بخش استفاده کنید:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

OpenClaw هر root مربوط به skill را یک مرز containment در نظر می‌گیرد. یک symlink زیر ~/.agents/skills، <workspace>/.agents/skills، <workspace>/skills، یا ~/.openclaw/skills وقتی target واقعی آن بیرون از آن root resolve شود نادیده گرفته می‌شود، مگر اینکه target به‌صراحت trusted باشد.

link را بررسی کنید:

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

اگر target عمدی است، هم root مستقیم skill و هم target مجاز symlink را configure کنید:

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

سپس یک session جدید شروع کنید یا منتظر بمانید watcher مربوط به skills refresh شود. اگر process در حال اجرا پیش از تغییر config شروع شده، gateway را restart کنید.

از targetهای گسترده مانند ~، /، یا یک پوشه پروژه synced کامل استفاده نکنید. allowSymlinkTargets را به root واقعی skill که directoryهای trusted SKILL.md را شامل می‌شود محدود نگه دارید.

اگر apply در Skill Workshop نیز باید از طریق همان pathهای trusted و symlinked workspace skill بنویسد، skills.workshop.allowSymlinkTargetWrites را فعال کنید. آن را برای rootهای skill مشترک فقط‌خواندنی غیرفعال نگه دارید.

مرتبط:

• config مربوط به Skills
• نمونه‌های Configuration

مصرف اضافی Anthropic 429 برای context طولانی لازم است

وقتی logها/خطاها شامل این مورد هستند از این بخش استفاده کنید: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

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

دنبال این موارد بگردید:

• مدل Anthropic انتخاب‌شده یک مدل 1M Claude 4.x با قابلیت GA است، یا مدل دارای params.context1m: true قدیمی است.
• credential فعلی Anthropic برای استفاده از context طولانی واجد شرایط نیست.
• requestها فقط در sessionهای طولانی/اجرای مدل‌هایی شکست می‌خورند که به مسیر context 1M نیاز دارند.

گزینه‌های رفع:

مرتبط:

• Anthropic
• مصرف token و هزینه‌ها
• چرا HTTP 429 از Anthropic می‌بینم؟

پاسخ‌های مسدودشده 403 از upstream

وقتی یک provider بالادستی LLM یک 403 عمومی مانند Your request was blocked برمی‌گرداند، از این بخش استفاده کنید.

فرض نکنید این همیشه یک مشکل configuration در OpenClaw است. پاسخ می‌تواند از یک لایه امنیتی بالادستی مانند CDN، WAF، قاعده bot-management، یا reverse proxy جلوی یک endpoint سازگار با OpenAI بیاید.

openclaw statusopenclaw gateway statusopenclaw logs --follow

دنبال این موارد بگردید:

• چندین مدل زیر یک provider یکسان به همان شکل شکست می‌خورند
• متن HTML یا security عمومی به‌جای خطای عادی API مربوط به provider
• eventهای security سمت provider در همان زمان request
• یک probe مستقیم کوچک با curl موفق می‌شود در حالی که requestهای عادی با شکل SDK شکست می‌خورند

وقتی evidence به block توسط WAF/CDN اشاره می‌کند، ابتدا filtering سمت provider را رفع کنید. یک قاعده allow یا skip با scope محدود برای path مربوط به API که OpenClaw استفاده می‌کند ترجیح دارد، و از غیرفعال کردن protection برای کل site خودداری کنید.

مرتبط:

• endpointهای سازگار با OpenAI
• Configuration مربوط به provider
• Logها

backend محلی سازگار با OpenAI از probeهای مستقیم عبور می‌کند اما اجراهای agent شکست می‌خورند

وقتی این موارد برقرار است از این بخش استفاده کنید:

• curl ... /v1/models کار می‌کند
• فراخوانی‌های مستقیم کوچک /v1/chat/completions کار می‌کنند
• اجرای مدل OpenClaw فقط در turnهای عادی agent شکست می‌خورد

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":"hi"}],"stream":false}'openclaw infer model run --model <provider/model> --prompt "hi" --jsonopenclaw logs --follow

دنبال این موارد بگردید:

• فراخوانی‌های مستقیم کوچک موفق می‌شوند، اما اجرای OpenClaw فقط روی promptهای بزرگ‌تر شکست می‌خورد
• خطاهای model_not_found یا 404، با وجود اینکه /v1/chat/completions مستقیم با همان bare model id کار می‌کند
• خطاهای backend درباره اینکه messages[].content باید string باشد
• هشدارهای متناوب incomplete turn detected ... stopReason=stop payloads=0 با یک backend محلی سازگار با OpenAI
• crashهای backend که فقط با تعداد prompt-token بزرگ‌تر یا promptهای کامل runtime مربوط به agent ظاهر می‌شوند

مرتبط:

• پیکربندی
• مدل‌های محلی
• نقاط پایانی سازگار با OpenAI

بدون پاسخ

اگر کانال‌ها فعال هستند اما چیزی پاسخ نمی‌دهد، پیش از اتصال دوباره هر چیز، مسیریابی و سیاست را بررسی کنید.

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

به دنبال این موارد باشید:

• جفت‌سازی در انتظار برای فرستندگان پیام مستقیم.
• دروازه‌گذاری اشاره در گروه (requireMention, mentionPatterns).
• ناهماهنگی‌های فهرست مجاز کانال/گروه.

نشانه‌های رایج:

• drop guild message (mention required → پیام گروه تا زمان اشاره نادیده گرفته می‌شود.
• pairing request → فرستنده به تأیید نیاز دارد.
• blocked / allowlist → فرستنده/کانال توسط سیاست فیلتر شده است.

مرتبط:

• عیب‌یابی کانال
• گروه‌ها
• جفت‌سازی

اتصال رابط کنترل داشبورد

وقتی داشبورد/رابط کنترل وصل نمی‌شود، 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 HTML مربوط به OpenClaw را برگرداند، Gateway کار می‌کند و مشکل باقی‌مانده احتمالاً کش مرورگر، یک پیوند عمیق قدیمی، یا وضعیت کهنه تب است. http://127.0.0.1:18789 را مستقیماً باز کنید و از داشبورد پیمایش کنید. اگر راه‌اندازی دوباره سرویس را در حال اجرا باقی نمی‌گذارد، openclaw gateway start را اجرا کنید و دوباره openclaw gateway status را بررسی کنید.

نقشه سریع کدهای جزئیات احراز هویت

از error.details.code در پاسخ ناموفق connect استفاده کنید تا اقدام بعدی را انتخاب کنید:

بررسی مهاجرت احراز هویت دستگاه نسخه ۲:

openclaw --versionopenclaw doctoropenclaw gateway status

اگر لاگ‌ها خطاهای nonce/امضا نشان می‌دهند، کلاینت متصل‌شونده را به‌روزرسانی و آن را تأیید کنید:

اگر openclaw devices rotate / revoke / remove به‌طور غیرمنتظره رد شد:

• نشست‌های توکن دستگاه جفت‌شده فقط می‌توانند دستگاه خودشان را مدیریت کنند، مگر اینکه فراخواننده operator.admin هم داشته باشد
• openclaw devices rotate --scope ... فقط می‌تواند محدوده‌های اپراتوری را درخواست کند که نشست فراخواننده از قبل دارد

مرتبط:

• پیکربندی (حالت‌های احراز هویت Gateway)
• رابط کنترل
• دستگاه‌ها
• دسترسی راه دور
• احراز هویت پراکسی مورد اعتماد

سرویس Gateway در حال اجرا نیست

از این مورد زمانی استفاده کنید که سرویس نصب شده اما فرایند پایدار نمی‌ماند.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # also scan system-level services

به دنبال این موارد باشید:

• Runtime: stopped همراه با راهنمایی‌های خروج.
• ناهماهنگی پیکربندی سرویس (Config (cli) در برابر Config (service)).
• تداخل‌های درگاه/شنونده.
• نصب‌های اضافی launchd/systemd/schtasks هنگام استفاده از --deep.
• راهنمایی‌های پاک‌سازی Other gateway-like services detected (best effort).

مرتبط:

• اجرای پس‌زمینه و ابزار فرایند
• پیکربندی
• Doctor

Gateway در macOS بی‌صدا از پاسخ‌گویی بازمی‌ایستد، سپس وقتی داشبورد را لمس می‌کنید از سر می‌گیرد

از این مورد زمانی استفاده کنید که کانال‌ها (Telegram، WhatsApp، و غیره) روی میزبان macOS برای چند دقیقه تا چند ساعت در هر نوبت ساکت می‌شوند، و به نظر می‌رسد Gateway همان لحظه‌ای که رابط کنترل را باز می‌کنید، با SSH وارد می‌شوید، یا به هر شکل دیگری با میزبان تعامل می‌کنید، دوباره برمی‌گردد. معمولاً در 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"

دنبال این موارد بگردید:

• یک یا چند بسته *-uncaught_exception.json در ~/.openclaw/logs/stability/ که 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 که state = not running را همراه با چند runs اخیر و یک کد خروج نشان می‌دهد، به‌ویژه وقتی فاصله بین خرابی و اجرای بعدی در حد یک ساعت باشد، نه چند ثانیه. launchd در macOS پس از یک موج خرابی، یک دروازه محافظت در برابر اجرای دوباره اعمال می‌کند که مستند نشده است و می‌تواند تا زمان یک محرک خارجی مانند ورود تعاملی، اتصال داشبورد، یا launchctl kickstart، دیگر به KeepAlive=true عمل نکند.

امضاهای رایج:

• یک بسته پایداری که error.code آن ENETDOWN یا یک کد هم‌خانواده است و پشته فراخوانی به lookupAndConnect / Socket.connect در net مربوط به Node اشاره می‌کند. OpenClaw 2026.5.26 و نسخه‌های جدیدتر این موارد را به‌عنوان خطاهای شبکه گذرای بی‌خطر دسته‌بندی می‌کنند تا دیگر به هندلر سطح بالای uncaught منتقل نشوند؛ اگر روی نسخه قدیمی‌تر هستید، ابتدا ارتقا دهید.
• دوره‌های طولانی سکوت که درست همان لحظه‌ای تمام می‌شوند که به رابط کاربری کنترل وصل می‌شوید یا با SSH وارد میزبان می‌شوید: فعالیت قابل مشاهده برای کاربر همان چیزی است که دروازه اجرای دوباره launchd را دوباره مسلح می‌کند، نه کاری که داشبورد با Gateway انجام می‌دهد.
• افزایش شمارنده runs در طول روز بدون خط متناظر received SIG*; shutting down در ~/Library/Logs/openclaw/gateway.log: خاموشی‌های تمیز یک سیگنال را ثبت می‌کنند؛ خرابی‌های گذرا این کار را نمی‌کنند.

چه باید کرد:

1. اگر نسخه‌ای قبل از 2026.5.26 را اجرا می‌کنید، Gateway را ارتقا دهید. پس از ارتقا، خطاهای آینده ENETDOWN به‌جای پایان دادن به فرایند، به‌صورت هشدار ثبت می‌شوند.

2. روی میزبان‌های Mac mini / دسکتاپ که قرار است سرور همیشه‌روشن باشند، فعالیت maintenance sleep را کاهش دهید:

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

   این کار نوسان زیربنایی درایور را به‌طور قابل توجهی کاهش می‌دهد، اما کاملا حذف نمی‌کند. سیستم همچنان می‌تواند صرف‌نظر از این پرچم‌ها، برای TCP keepalive و نگهداری mDNS برخی maintenance sleepها را انجام دهد.

3. یک watchdog زنده‌بودن اضافه کنید تا موج خرابی آینده که توسط launchd متوقف می‌شود، سریع شناسایی شود:

   # Example launchd-aware liveness check, suitable for a 5-minute cron or LaunchAgentstate=$(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

   هدف این است که دروازه اجرای دوباره از بیرون دوباره مسلح شود؛ KeepAlive=true به‌تنهایی پس از یک موج خرابی در macOS کافی نیست.

مرتبط:

• نکته‌های پلتفرم macOS
• ثبت گزارش
• Doctor

خروج 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 در آخرین بسته پایداری.
• Memory pressure: همراه با critical/rss_threshold، critical/heap_threshold، یا critical/rss_growth.
• مقادیر V8 heap: نزدیک به حد heap.
• ورودی‌های Largest session files: مانند agents/<agent>/sessions/<session>.jsonl یا sessions/<session>.jsonl.
• شمارنده‌های حافظه cgroup در Linux وقتی Gateway داخل یک کانتینر یا سرویس با محدودیت حافظه اجرا می‌شود.

امضاهای رایج:

• critical memory pressure bundle written کمی قبل از راه‌اندازی مجدد ظاهر می‌شود → OpenClaw یک بسته پایداری پیش از OOM ثبت کرده است. آن را با openclaw gateway stability --bundle latest بررسی کنید.
• memory pressure: level=critical ... memoryPressureSnapshot=disabled در لاگ‌های Gateway ظاهر می‌شود → OpenClaw فشار بحرانی حافظه را تشخیص داده، اما snapshot پایداری پیش از OOM خاموش است.
• Largest session files: به یک مسیر transcript ویرایش‌شده بسیار بزرگ اشاره می‌کند → تاریخچه نگهداری‌شده session را کاهش دهید، رشد session را بررسی کنید، یا پیش از راه‌اندازی مجدد transcriptهای قدیمی را از store فعال خارج کنید.
• بایت‌های استفاده‌شده در V8 heap: نزدیک به حد heap هستند → فشار prompt/session را کم کنید، کار هم‌زمان را کاهش دهید، یا فقط پس از تأیید اینکه بار کاری مورد انتظار است، حد heap مربوط به Node را افزایش دهید.
• Memory pressure: critical/rss_growth → حافظه در یک پنجره نمونه‌برداری به‌سرعت رشد کرده است. آخرین لاگ‌ها را برای یک import بزرگ، خروجی بی‌مهار ابزار، تلاش‌های تکراری، یا مجموعه‌ای از کارهای agent در صف بررسی کنید.
• فشار بحرانی حافظه در لاگ‌ها دیده می‌شود اما بسته‌ای وجود ندارد → این حالت پیش‌فرض است. diagnostics.memoryPressureSnapshot: true را تنظیم کنید تا در رویدادهای آینده فشار بحرانی حافظه، بسته پایداری پیش از OOM ثبت شود.

بسته پایداری بدون payload است. این بسته شواهد عملیاتی حافظه و مسیرهای نسبی فایل به‌صورت ویرایش‌شده را شامل می‌شود، نه متن پیام، بدنه‌های Webhook، اعتبارنامه‌ها، توکن‌ها، کوکی‌ها یا شناسه‌های خام session. به‌جای کپی کردن لاگ‌های خام، خروجی diagnostics را به گزارش‌های باگ پیوست کنید.

مرتبط:

• سلامت Gateway
• خروجی diagnostics
• Sessionها

Gateway پیکربندی نامعتبر را رد کرد

وقتی راه‌اندازی Gateway با Invalid config شکست می‌خورد یا لاگ‌های hot reload می‌گویند یک ویرایش نامعتبر را نادیده گرفته است، از این بخش استفاده کنید.

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

دنبال این موارد بگردید:

• Invalid config at ...
• config reload skipped (invalid config): ...
• Config write rejected: ...
• یک فایل دارای timestamp با نام openclaw.json.rejected.* کنار پیکربندی فعال
• یک فایل دارای timestamp با نام openclaw.json.clobbered.* اگر doctor --fix یک ویرایش مستقیم خراب را تعمیر کرده باشد
• 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

مرتبط:

• پیکربندی
• پیکربندی: hot reload
• پیکربندی: اعتبارسنجی سخت‌گیرانه
• Doctor

هشدارهای probe برای Gateway

وقتی openclaw gateway probe به چیزی می‌رسد، اما همچنان یک بلوک هشدار چاپ می‌کند، از این بخش استفاده کنید.

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

دنبال این موارد بگردید:

• warnings[].code و primaryTargetId در خروجی JSON.
• اینکه هشدار درباره fallback مربوط به SSH، چند Gateway، scopeهای گمشده، یا auth refهای حل‌نشده است.

امضاهای رایج:

• SSH tunnel failed to start; falling back to direct probes. → راه‌اندازی SSH شکست خورد، اما فرمان همچنان اهداف پیکربندی‌شده/loopback مستقیم را امتحان کرد.
• multiple reachable gateway identities detected → Gatewayهای متمایز پاسخ دادند، یا OpenClaw نتوانست ثابت کند اهداف در دسترس همان Gateway هستند. یک تونل SSH، نشانی proxy، یا نشانی remote پیکربندی‌شده به همان Gateway، حتی وقتی پورت‌های transport متفاوت باشند، به‌عنوان یک Gateway با چند transport در نظر گرفته می‌شود.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → اتصال برقرار شد، اما RPC جزئیات به‌دلیل scope محدود شده است؛ هویت دستگاه را pair کنید یا از اعتبارنامه‌هایی با operator.read استفاده کنید.
• Gateway accepted the WebSocket connection, but follow-up read diagnostics failed → اتصال برقرار شد، اما مجموعه کامل RPCهای diagnostic timeout شد یا شکست خورد. این را به‌عنوان یک Gateway در دسترس با diagnostics تنزل‌یافته در نظر بگیرید؛ connect.ok و connect.rpcOk را در خروجی --json مقایسه کنید.
• Capability: pairing-pending یا gateway closed (1008): pairing required → Gateway پاسخ داد، اما این client هنوز پیش از دسترسی عادی operator به pairing/approval نیاز دارد.
• متن هشدار SecretRef حل‌نشده gateway.auth.* / gateway.remote.* → ماده auth در این مسیر فرمان برای هدف شکست‌خورده در دسترس نبود.

مرتبط:

• Gateway
• چند Gateway روی یک میزبان
• دسترسی remote

کانال وصل است، اما پیام‌ها جریان ندارند

اگر وضعیت کانال connected است اما جریان پیام قطع شده، روی policy، permissionها و قواعد تحویل مخصوص کانال تمرکز کنید.

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

دنبال این موارد بگردید:

• policy مربوط به DM (pairing، allowlist، open، disabled).
• allowlist گروه و الزامات mention.
• permissionها/scopeهای گمشده API کانال.

امضاهای رایج:

• mention required → پیام به‌دلیل policy مربوط به mention گروه نادیده گرفته شد.
• ردپاهای pairing / pending approval → فرستنده تأیید نشده است.
• missing_scope، not_in_channel، Forbidden، 401/403 → مشکل auth/permission کانال.

مرتبط:

• عیب‌یابی کانال
• Discord
• Telegram
• WhatsApp

تحویل Cron و Heartbeat

اگر Cron یا Heartbeat اجرا نشد یا تحویل داده نشد، ابتدا وضعیت scheduler و سپس هدف تحویل را بررسی کنید.

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 آنلاین با قابلیت‌های مورد انتظار.
• اعطای مجوزهای سیستم‌عامل برای دوربین/میکروفون/مکان/صفحه‌نمایش.
• تأییدهای exec و وضعیت allowlist.

امضاهای رایج:

• NODE_BACKGROUND_UNAVAILABLE → برنامه node باید در پیش‌زمینه باشد.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → مجوز سیستم‌عامل موجود نیست.
• SYSTEM_RUN_DENIED: approval required → تأیید exec در انتظار است.
• SYSTEM_RUN_DENIED: allowlist miss → فرمان توسط allowlist مسدود شده است.

مرتبط:

• تأییدهای exec
• عیب‌یابی Node
• Nodes

ابزار مرورگر شکست می‌خورد

وقتی کنش‌های ابزار مرورگر شکست می‌خورند اما خود gateway سالم است، از این استفاده کنید.

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

دنبال این موارد بگردید:

• اینکه آیا plugins.allow تنظیم شده و شامل browser هست یا نه.
• مسیر اجرایی معتبر مرورگر.
• دسترس‌پذیری پروفایل CDP.
• دسترس‌پذیری Chrome محلی برای پروفایل‌های existing-session / user.

مرتبط:

• مرورگر (مدیریت‌شده توسط OpenClaw)
• عیب‌یابی مرورگر

اگر ارتقا دادید و چیزی ناگهان خراب شد

بیشتر خرابی‌های پس از ارتقا ناشی از drift پیکربندی یا اعمال شدن پیش‌فرض‌های سخت‌گیرانه‌تر است.

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

اگر پیکربندی سرویس و runtime پس از بررسی‌ها همچنان با هم اختلاف دارند، metadata سرویس را از همان دایرکتوری profile/state دوباره نصب کنید:

openclaw gateway install --forceopenclaw gateway restart

مرتبط:

• احراز هویت
• exec پس‌زمینه و ابزار فرایند
• جفت‌سازی تحت مالکیت Gateway

مرتبط

• Doctor
• پرسش‌های متداول
• Runbook Gateway