عیب‌یابی

• model_not_found با یک سرور محلی به سبک MLX/vLLM → بررسی کنید baseUrl شامل /v1 باشد، api برای backendهای /v1/chat/completions برابر "openai-completions" باشد، و models.providers.<provider>.models[].id همان شناسه bare محلی provider باشد. آن را یک بار با پیشوند provider انتخاب کنید، برای مثال mlx/mlx-community/Qwen3-30B-A3B-6bit؛ ورودی کاتالوگ را به صورت mlx-community/Qwen3-30B-A3B-6bit نگه دارید.
• messages[...].content: invalid type: sequence, expected a string → backend بخش‌های محتوای ساخت‌یافته Chat Completions را رد می‌کند. رفع: models.providers.<provider>.models[].compat.requiresStringContent: true را تنظیم کنید.
• incomplete turn detected ... stopReason=stop payloads=0 → backend درخواست Chat Completions را کامل کرده اما برای آن نوبت هیچ متن دستیار قابل‌مشاهده برای کاربر برنگردانده است. OpenClaw نوبت‌های خالی سازگار با OpenAI و ایمن برای replay را یک بار دوباره امتحان می‌کند؛ شکست‌های پایدار معمولا یعنی backend محتوای خالی/غیرمتنی تولید می‌کند یا متن پاسخ نهایی را سرکوب می‌کند.
• درخواست‌های کوچک مستقیم موفق می‌شوند، اما اجرای عامل OpenClaw با crashهای backend/model شکست می‌خورد (برای مثال Gemma روی بعضی buildهای inferrs) → ترابری OpenClaw احتمالا از قبل درست است؛ backend روی شکل prompt بزرگ‌تر runtime عامل شکست می‌خورد.
• شکست‌ها پس از غیرفعال کردن ابزارها کمتر می‌شوند اما از بین نمی‌روند → schemaهای ابزار بخشی از فشار بودند، اما مشکل باقی‌مانده همچنان ظرفیت مدل/سرور upstream یا یک bug در backend است.

1. برای backendهای Chat Completions فقط-string، compat.requiresStringContent: true را تنظیم کنید.
2. برای مدل‌ها/backendهایی که نمی‌توانند سطح schema ابزار OpenClaw را قابل‌اعتماد مدیریت کنند، compat.supportsTools: false را تنظیم کنید.
3. فشار prompt را تا جای ممکن کاهش دهید: bootstrap کوچک‌تر workspace، تاریخچه نشست کوتاه‌تر، مدل محلی سبک‌تر، یا backend با پشتیبانی long-context قوی‌تر.
4. اگر درخواست‌های کوچک مستقیم همچنان پاس می‌شوند اما نوبت‌های عامل OpenClaw هنوز داخل backend crash می‌کنند، آن را محدودیت upstream سرور/مدل در نظر بگیرید و با شکل payload پذیرفته‌شده، آنجا یک repro ثبت کنید.

• device identity required → context ناامن یا احراز هویت دستگاه موجود نیست.
• origin not allowed → مقدار Origin مرورگر در gateway.controlUi.allowedOrigins نیست (یا از یک origin مرورگر غیر-loopback بدون allowlist صریح وصل می‌شوید).
• device nonce required / device nonce mismatch → client جریان احراز هویت دستگاه مبتنی بر challenge را کامل نمی‌کند (connect.challenge + device.nonce).
• device signature invalid / device signature expired → client payload اشتباه (یا timestamp کهنه) را برای handshake فعلی امضا کرده است.
• AUTH_TOKEN_MISMATCH با canRetryWithDeviceToken=true → client می‌تواند یک retry مورداعتماد با توکن دستگاه cacheشده انجام دهد.
• آن retry با cached-token همان مجموعه scope cacheشده ذخیره‌شده همراه با توکن دستگاه pairشده را دوباره استفاده می‌کند. فراخوان‌هایی که deviceToken صریح / scopes صریح دارند، مجموعه scope درخواستی خود را نگه می‌دارند.
• بیرون از آن مسیر retry، تقدم احراز هویت اتصال به‌ترتیب token/password مشترک صریح، سپس deviceToken صریح، سپس توکن دستگاه ذخیره‌شده، سپس توکن bootstrap است.
• در مسیر async Tailscale Serve Control UI، تلاش‌های ناموفق برای همان {scope, ip} پیش از ثبت شکست توسط limiter سریال‌سازی می‌شوند. بنابراین دو retry بد هم‌زمان از همان client می‌توانند به‌جای دو mismatch ساده، در تلاش دوم retry later نشان دهند.
• too many failed authentication attempts (retry later) از یک client مرورگر-origin loopback → شکست‌های تکراری از همان Origin نرمال‌شده به طور موقت قفل می‌شوند؛ یک origin localhost دیگر از bucket جداگانه استفاده می‌کند.
• unauthorized تکراری پس از آن retry → drift توکن مشترک/توکن دستگاه؛ پیکربندی توکن را refresh کنید و در صورت نیاز توکن دستگاه را دوباره approve/rotate کنید.
• gateway connect failed: → هدف host/port/url اشتباه است.

• Gateway start blocked: set gateway.mode=local یا existing config is missing gateway.mode → حالت Gateway محلی فعال نیست، یا فایل پیکربندی بازنویسی شده و gateway.mode را از دست داده است. رفع: gateway.mode="local" را در پیکربندی خود تنظیم کنید، یا openclaw onboard --mode local / openclaw setup را دوباره اجرا کنید تا پیکربندی مورد انتظار حالت محلی دوباره مهر شود. اگر OpenClaw را از طریق Podman اجرا می‌کنید، مسیر پیش‌فرض پیکربندی ~/.openclaw/openclaw.json است.
• refusing to bind gateway ... without auth → اتصال non-loopback بدون مسیر معتبر احراز هویت Gateway (توکن/رمز عبور، یا trusted-proxy در جایی که پیکربندی شده است).
• another gateway instance is already listening / EADDRINUSE → تداخل پورت.
• Other gateway-like services detected (best effort) → واحدهای قدیمی یا موازی launchd/systemd/schtasks وجود دارند. بیشتر راه‌اندازی‌ها باید برای هر ماشین یک Gateway نگه دارند؛ اگر واقعاً به بیش از یکی نیاز دارید، پورت‌ها + پیکربندی/وضعیت/workspace را جدا کنید. /gateway#multiple-gateways-same-host را ببینید.
• System-level OpenClaw gateway service detected از doctor → یک واحد سیستم systemd وجود دارد در حالی که سرویس سطح کاربر وجود ندارد. قبل از اینکه به doctor اجازه دهید یک سرویس کاربری نصب کند، نسخه تکراری را حذف یا غیرفعال کنید، یا اگر واحد سیستم supervisor مورد نظر است OPENCLAW_SERVICE_REPAIR_POLICY=external را تنظیم کنید.
• Gateway service port does not match current gateway config → supervisor نصب‌شده هنوز --port قدیمی را pin کرده است. openclaw doctor --fix یا openclaw gateway install --force را اجرا کنید، سپس سرویس Gateway را دوباره راه‌اندازی کنید.

• پیکربندی هنگام راه‌اندازی، hot reload، یا نوشتن تحت مالکیت OpenClaw اعتبارسنجی نشد.
• راه‌اندازی Gateway به‌جای بازنویسی openclaw.json به‌صورت بسته شکست می‌خورد.
• hot reload ویرایش‌های خارجی نامعتبر را رد می‌کند و پیکربندی runtime فعلی را فعال نگه می‌دارد.
• نوشتن‌های تحت مالکیت OpenClaw پیش از commit payloadهای نامعتبر/مخرب را رد می‌کنند و .rejected.* را ذخیره می‌کنند.
• openclaw doctor --fix مالک تعمیر است. می‌تواند پیشوندهای غیر JSON را حذف کند یا آخرین نسخه سالم شناخته‌شده را بازیابی کند، در حالی که payload ردشده را به‌صورت .clobbered.* حفظ می‌کند.

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

• .clobbered.* وجود دارد → doctor هنگام تعمیر پیکربندی فعال، یک ویرایش خارجی خراب را حفظ کرده است.
• .rejected.* وجود دارد → یک نوشتن پیکربندی تحت مالکیت OpenClaw پیش از commit در schema یا بررسی‌های clobber شکست خورده است.
• Config write rejected: → نوشتن تلاش کرده shape الزامی را حذف کند، فایل را به‌شدت کوچک کند، یا پیکربندی نامعتبر را persist کند.
• config reload skipped (invalid config): → یک ویرایش مستقیم در اعتبارسنجی شکست خورد و توسط Gateway در حال اجرا نادیده گرفته شد.
• Invalid config at ... → راه‌اندازی پیش از boot شدن سرویس‌های Gateway شکست خورد.
• missing-meta-vs-last-good، gateway-mode-missing-vs-last-good، یا size-drop-vs-last-good:* → یک نوشتن تحت مالکیت OpenClaw رد شد چون نسبت به backup آخرین نسخه سالم شناخته‌شده، فیلدها یا اندازه را از دست داده بود.
• Config last-known-good promotion skipped → candidate شامل placeholderهای secret سانسورشده مانند *** بود.

1. openclaw doctor --fix را اجرا کنید تا doctor پیکربندی دارای prefix/clobbered را تعمیر کند یا آخرین نسخه سالم شناخته‌شده را بازیابی کند.
2. فقط کلیدهای مورد نظر را از .clobbered.* یا .rejected.* کپی کنید، سپس آن‌ها را با openclaw config set یا config.patch اعمال کنید.
3. قبل از راه‌اندازی مجدد، openclaw config validate را اجرا کنید.
4. اگر دستی ویرایش می‌کنید، پیکربندی کامل JSON5 را نگه دارید، نه فقط شیء جزئی‌ای که می‌خواستید تغییر دهید.

• cron: scheduler disabled; jobs will not run automatically → cron غیرفعال است.
• cron: timer tick failed → تیک زمان‌بند ناموفق بود؛ خطاهای فایل/لاگ/زمان اجرا را بررسی کنید.
• heartbeat skipped همراه با reason=quiet-hours → خارج از بازه ساعات فعال است.
• heartbeat skipped همراه با reason=empty-heartbeat-file → HEARTBEAT.md وجود دارد اما فقط شامل خط‌های خالی / سربرگ‌های مارک‌داون است، بنابراین OpenClaw فراخوانی مدل را رد می‌کند.
• heartbeat skipped همراه با reason=no-tasks-due → HEARTBEAT.md شامل یک بلوک tasks: است، اما هیچ‌کدام از کارها در این تیک موعد اجرا ندارند.
• heartbeat: unknown accountId → شناسه حساب برای مقصد تحویل heartbeat نامعتبر است.
• heartbeat skipped همراه با reason=dm-blocked → مقصد heartbeat به یک مقصد سبک DM resolve شده، در حالی که agents.defaults.heartbeat.directPolicy (یا override هر عامل) روی block تنظیم شده است.

• unknown command "browser" یا unknown command 'browser' → Plugin مرورگر بسته‌بندی‌شده توسط plugins.allow مستثنی شده است.
• ابزار مرورگر وجود ندارد / در دسترس نیست در حالی که browser.enabled=true → plugins.allow شامل browser نیست، پس Plugin هرگز بارگذاری نشده است.
• Failed to start Chrome CDP on port → فرایند مرورگر اجرا نشد.
• browser.executablePath not found → مسیر پیکربندی‌شده نامعتبر است.
• browser.cdpUrl must be http(s) or ws(s) → نشانی CDP پیکربندی‌شده از طرح پشتیبانی‌نشده‌ای مثل file: یا ftp: استفاده می‌کند.
• browser.cdpUrl has invalid port → نشانی CDP پیکربندی‌شده پورت بد یا خارج از محدوده دارد.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → نصب فعلی gateway وابستگی اصلی زمان اجرای مرورگر را ندارد؛ OpenClaw را دوباره نصب یا به‌روزرسانی کنید، سپس Gateway را راه‌اندازی مجدد کنید. اسنپ‌شات‌های ARIA و اسکرین‌شات‌های پایه صفحه همچنان می‌توانند کار کنند، اما ناوبری، اسنپ‌شات‌های AI، اسکرین‌شات‌های عنصر با انتخابگر CSS و خروجی PDF در دسترس نمی‌مانند.

• Could not find DevToolsActivePort for chrome → Chrome MCP existing-session هنوز نتوانسته به دایرکتوری داده مرورگر انتخاب‌شده attach شود. صفحه inspect مرورگر را باز کنید، remote debugging را فعال کنید، مرورگر را باز نگه دارید، اولین درخواست attach را تأیید کنید، سپس دوباره تلاش کنید. اگر وضعیت ورود لازم نیست، پروفایل مدیریت‌شده openclaw را ترجیح دهید.
• No Chrome tabs found for profile="user" → پروفایل attach کروم MCP هیچ تب Chrome محلی بازی ندارد.
• Remote CDP for profile "<name>" is not reachable → نقطه پایانی CDP راه دور پیکربندی‌شده از میزبان Gateway قابل دسترسی نیست.
• Browser attachOnly is enabled ... not reachable یا Browser attachOnly is enabled and CDP websocket ... is not reachable → پروفایل فقط-attach هدف قابل دسترسی ندارد، یا نقطه پایانی HTTP پاسخ داده اما WebSocket مربوط به CDP همچنان باز نشده است.

• fullPage is not supported for element screenshots → درخواست اسکرین‌شات --full-page را با --ref یا --element ترکیب کرده است.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → فراخوانی‌های اسکرین‌شات Chrome MCP / existing-session باید از capture صفحه یا --ref اسنپ‌شات استفاده کنند، نه CSS --element.
• existing-session file uploads do not support element selectors; use ref/inputRef. → hookهای آپلود Chrome MCP به refهای اسنپ‌شات نیاز دارند، نه انتخابگرهای CSS.
• existing-session file uploads currently support one file at a time. → در پروفایل‌های Chrome MCP برای هر فراخوانی یک آپلود ارسال کنید.
• existing-session dialog handling does not support timeoutMs. → hookهای دیالوگ در پروفایل‌های Chrome MCP از overrideهای timeout پشتیبانی نمی‌کنند.
• existing-session type does not support timeoutMs overrides. → برای act:type در پروفایل‌های profile="user" / Chrome MCP existing-session، timeoutMs را حذف کنید، یا وقتی timeout سفارشی لازم است از پروفایل مرورگر مدیریت‌شده/CDP استفاده کنید.
• existing-session evaluate does not support timeoutMs overrides. → برای act:evaluate در پروفایل‌های profile="user" / Chrome MCP existing-session، timeoutMs را حذف کنید، یا وقتی timeout سفارشی لازم است از پروفایل مرورگر مدیریت‌شده/CDP استفاده کنید.
• response body is not supported for existing-session profiles yet. → responsebody همچنان به مرورگر مدیریت‌شده یا پروفایل CDP خام نیاز دارد.
• overrideهای کهنه viewport / dark-mode / locale / offline روی پروفایل‌های attach-only یا CDP راه دور → openclaw browser stop --browser-profile <name> را اجرا کنید تا نشست کنترل فعال بسته شود و وضعیت emulation مربوط به Playwright/CDP بدون راه‌اندازی مجدد کل Gateway آزاد شود.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

چه چیزی را بررسی کنید:

• اگر gateway.mode=remote باشد، فراخوانی‌های CLI ممکن است مقصدشان remote باشد در حالی که سرویس محلی شما سالم است.
• فراخوانی‌های صریح --url به اعتبارنامه‌های ذخیره‌شده fallback نمی‌کنند.

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

• gateway connect failed: → مقصد نشانی اشتباه است.
• unauthorized → نقطه پایانی قابل دسترسی است اما احراز هویت اشتباه است.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

چه چیزی را بررسی کنید:

• bindهای غیر local loopback (lan، tailnet، custom) به یک مسیر معتبر احراز هویت gateway نیاز دارند: احراز هویت با توکن/رمز عبور مشترک، یا استقرار trusted-proxy غیر local loopback که درست پیکربندی شده باشد.
• کلیدهای قدیمی مثل gateway.token جایگزین gateway.auth.token نمی‌شوند.

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

• refusing to bind gateway ... without auth → bind غیر local loopback بدون مسیر معتبر احراز هویت gateway.
• Connectivity probe: failed در حالی که زمان اجرا فعال است → gateway زنده است اما با auth/url فعلی قابل دسترسی نیست.

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

چه چیزی را بررسی کنید:

• تأییدهای در انتظار دستگاه برای dashboard/nodes.
• تأییدهای در انتظار جفت‌سازی DM پس از تغییرات خط‌مشی یا هویت.

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

• device identity required → احراز هویت دستگاه برآورده نشده است.
• pairing required → فرستنده/دستگاه باید تأیید شود.