عیب‌یابی

این راهنمای عملیاتی عمیق است. برای جریان عیب‌یابی سریع، ابتدا از /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

موارد زیر را بررسی کنید:

• Update restart در openclaw status / openclaw status --all. واگذاری‌های در انتظار یا ناموفق شامل فرمان بعدی برای اجرا هستند.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix زیر Channels: پیکربندی کانال همچنان وجود دارد، اما ثبت 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

موارد زیر را بررسی کنید:

• protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n> در گزارش‌های Gateway.
• Established clients: در openclaw gateway status --deep یا Gateway clients در openclaw doctor --deep: سرویس‌گیرنده‌های فعال TCP متصل به پورت Gateway، همراه با PIDها و خطوط فرمان در صورت اجازه سیستم‌عامل.
• فرایند سرویس‌گیرنده‌ای که خط فرمان آن به نصب یا لفاف جدیدتر OpenClaw اشاره می‌کند که از آن بازگردانی کرده‌اید.

راه‌حل:

1. فرایند منسوخ سرویس‌گیرنده OpenClaw را که gateway status --deep نشان می‌دهد متوقف یا دوباره راه‌اندازی کنید.
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 یک مدل 1M Claude 4.x دارای قابلیت GA است (Opus 4.6/4.7/4.8، Sonnet 4.6)، یا پیکربندی مدل همچنان شامل params.context1m: true قدیمی است.
• اعتبارنامه فعلی Anthropic واجد شرایط استفاده از زمینه طولانی نیست.
• درخواست‌ها فقط در نشست‌های طولانی/اجرای مدل‌هایی که به مسیر زمینه 1M نیاز دارند شکست می‌خورند.

گزینه‌های رفع مشکل:

مرتبط:

• Anthropic
• مصرف توکن و هزینه‌ها
• چرا خطای HTTP 429 از Anthropic مشاهده می‌کنم؟

پاسخ‌های مسدودشده 403 از بالادست

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

فرض نکنید که این مورد همیشه مشکل پیکربندی OpenClaw است. پاسخ می‌تواند از لایه امنیتی بالادستی مانند CDN، WAF، قاعده مدیریت ربات یا پراکسی معکوس در جلوی نقطه پایانی سازگار با OpenAI بیاید.

openclaw statusopenclaw gateway statusopenclaw logs --follow

موارد زیر را بررسی کنید:

• چند مدل زیر یک ارائه‌دهنده به شیوه یکسانی شکست می‌خورند.
• به‌جای خطای معمول API ارائه‌دهنده، HTML یا متن امنیتی عمومی نمایش داده می‌شود.
• رویدادهای امنیتی سمت ارائه‌دهنده برای همان زمان درخواست وجود دارند.
• یک کاوش مستقیم و کوچک curl موفق می‌شود، اما درخواست‌هایی با ساختار عادی SDK شکست می‌خورند.

وقتی شواهد به مسدودسازی WAF/CDN اشاره دارند، ابتدا فیلتر سمت ارائه‌دهنده را اصلاح کنید. یک قاعده مجازسازی یا رد شدن با دامنه محدود برای مسیر API مورد استفاده OpenClaw ترجیح دارد؛ از غیرفعال کردن حفاظت برای کل سایت خودداری کنید.

مرتبط:

• نقاط پایانی سازگار با 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 باید رشته باشد.
• هشدارهای متناوب incomplete turn detected ... stopReason=stop payloads=0 با یک پشتیبان محلی سازگار با OpenAI.
• خرابی‌های پشتیبان که فقط با تعداد بیشتر توکن‌های پرامپت یا پرامپت‌های کامل زمان‌اجرای عامل رخ می‌دهند.

مرتبط:

• پیکربندی
• مدل‌های محلی
• نقاط پایانی سازگار با 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 استفاده کنید:

بررسی مهاجرت احراز هویت دستگاه v2:

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   # سرویس‌های سطح سیستم را نیز اسکن کنید

موارد زیر را جست‌وجو کنید:

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

مطالب مرتبط:

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

Gateway در macOS بی‌صدا از پاسخ‌گویی بازمی‌ایستد و با لمس داشبورد دوباره ادامه می‌دهد

برای زمانی استفاده کنید که کانال‌ها (Telegram، WhatsApp و غیره) روی یک میزبان macOS هر بار از چند دقیقه تا چند ساعت بی‌صدا می‌شوند و به‌نظر می‌رسد Gateway درست در لحظه‌ای که Control UI را باز می‌کنید، از طریق 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 پس از وقوع متوالی چند خرابی، یک سازوکار حفاظتی مستندنشدۀ اجرای مجدد اعمال می‌کند که ممکن است رعایت KeepAlive=true را متوقف کند تا زمانی که یک محرک خارجی مانند ورود تعاملی، اتصال داشبورد یا launchctl kickstart آن را دوباره فعال کند.

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

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

اقدامات لازم:

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

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

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

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

3. یک ناظر زنده‌بودن اضافه کنید تا اگر در آینده launchd پس از وقوع متوالی خرابی‌ها فرایند را متوقف نگه داشت، مشکل به‌سرعت شناسایی شود:

   # نمونه بررسی زنده‌بودن آگاه از launchd، مناسب برای Cron پنج‌دقیقه‌ای یا 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

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

مرتبط:

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

حلقه نظارتی launchd در macOS با LaunchAgentهای تکراری Gateway/node

این بخش را زمانی استفاده کنید که یک نصب macOS هر چند ثانیه یک‌بار پیوسته راه‌اندازی مجدد می‌شود، بررسی‌های سلامت openclaw میان وضعیت سالم و دردسترس‌نبودن نوسان می‌کنند و ارسال کانال متوقف می‌شود، با اینکه به‌نظر می‌رسد سرویس در حال اجرا است.

این وضعیت در نصب‌های قدیمی‌تری مشاهده شده است که در آن‌ها هر دو LaunchAgent یعنی ai.openclaw.gateway و ai.openclaw.node فعال بودند و هرکدام 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

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

• وجود بیش از یک PID برای Gateway در نمونه 30ثانیه‌ای، به‌جای یک فرایند پایدار.
• EADDRINUSE، another gateway instance is already listening یا خطوط تکراری راه‌اندازی مجدد/واگذاری کنترل در gateway.log.
• بارگذاری هم‌زمان هر دو ~/Library/LaunchAgents/ai.openclaw.gateway.plist و ~/Library/LaunchAgents/ai.openclaw.node.plist روی میزبانی که باید فقط یک سرویس مدیریت‌شده Gateway را اجرا کند.

اقدامات لازم:

1. اگر این میزبان باید فقط سرویس Gateway را اجرا کند، سرویس مدیریت‌شده node را از طریق OpenClaw حذف کنید. اگر برای قابلیت‌های 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
• CLI مربوط به Gateway

خروج 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 در گزارش‌های Gateway ظاهر می‌شود ← OpenClaw فشار بحرانی حافظه را تشخیص داده و داده‌های حافظه درون‌فرایندی موجود را ثبت کرده است.
• Largest session files: به مسیر رونوشت پالایش‌شده بسیار بزرگی اشاره می‌کند ← تاریخچه نشست نگه‌داری‌شده را کاهش دهید، رشد نشست را بررسی کنید، یا پیش از راه‌اندازی مجدد، رونوشت‌های قدیمی را از مخزن فعال خارج کنید.
• بایت‌های مصرف‌شده V8 heap: به محدودیت heap نزدیک‌اند ← ابتدا فشار پرامپت/نشست یا حجم کار هم‌زمان را کاهش دهید. برای سرویس مدیریت‌شده، Gateway heap: را در openclaw gateway status بررسی کنید؛ اگر مقدار آن not set است، فراداده قدیمی سرویس را با openclaw gateway install --force دوباره تولید کنید. متغیر NODE_OPTIONS در پوسته محیطی عمداً نادیده گرفته می‌شود. فقط پس از تأیید حجم کار پایدار و باقی‌گذاشتن فضای کافی برای حافظه بومی، از بازنویسی صریح heap در سطح ناظر استفاده کنید.
• Memory pressure: critical/rss_growth ← حافظه درون یک بازه نمونه‌برداری به‌سرعت رشد کرده است. جدیدترین گزارش‌ها را برای واردسازی بزرگ، خروجی مهارنشده ابزار، تلاش‌های مجدد تکراری، یا دسته‌ای از کارهای صف‌شده عامل بررسی کنید.
• فشار بحرانی حافظه در گزارش‌ها ظاهر می‌شود، اما بسته‌ای وجود ندارد ← پس از رویداد، openclaw gateway diagnostics export را برای شواهد عملیاتی موجود ثبت کنید.

بسته پایداری فاقد payload است. این بسته شامل شواهد عملیاتی حافظه و مسیرهای نسبی پالایش‌شده فایل است، نه متن پیام، بدنه‌های 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.* دارای برچسب زمانی در کنار پیکربندی فعال.
• یک فایل 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

مرتبط:

• پیکربندی
• پیکربندی: بارگذاری مجدد فوری
• پیکربندی: اعتبارسنجی سخت‌گیرانه
• Doctor

هشدارهای کاوش Gateway

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

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

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

• warnings[].code و primaryTargetId در خروجی JSON.
• اینکه هشدار دربارهٔ بازگشت جایگزین SSH، چند Gateway، محدوده‌های دسترسی مفقود، یا ارجاع‌های احراز هویت حل‌نشده است.

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

• SSH tunnel failed to start; falling back to direct probes. ← راه‌اندازی SSH شکست خورده، اما فرمان همچنان اهداف مستقیم پیکربندی‌شده/حلقهٔ محلی را امتحان کرده است.
• multiple reachable gateway identities detected ← Gatewayهای متمایز پاسخ داده‌اند، یا OpenClaw نتوانسته ثابت کند اهداف در دسترس همان Gateway هستند. تونل SSH، نشانی پروکسی، یا نشانی راه دور پیکربندی‌شده به همان Gateway، حتی در صورت تفاوت پورت‌های انتقال، یک 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 در دسترس با قابلیت‌های تشخیصی تضعیف‌شده در نظر بگیرید؛ connect.ok و connect.rpcOk را در خروجی --json مقایسه کنید.
• Capability: pairing-pending یا gateway closed (1008): pairing required ← Gateway پاسخ داده، اما این کارخواه همچنان پیش از دسترسی عادی اپراتور به جفت‌سازی/تأیید نیاز دارد.
• متن هشدار SecretRef حل‌نشدهٔ gateway.auth.* / gateway.remote.* ← اطلاعات احراز هویت در این مسیر فرمان برای هدف ناموفق در دسترس نبوده است.

مرتبط:

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

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

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

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

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

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

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

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

مرتبط:

• تأییدهای اجرا
• عیب‌یابی Node
• Nodeها

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

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

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

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

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

مرتبط:

• مرورگر (مدیریت‌شده توسط 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