openclaw doctor

بررسی‌های سلامت و رفع سریع مشکلات Gateway، کانال‌ها، Pluginها، Skills، مسیریابی مدل، وضعیت محلی و مهاجرت‌های پیکربندی. هرگاه چیزی مطابق انتظار عمل نمی‌کند و می‌خواهید یک فرمان علت مشکل را توضیح دهد، از آن استفاده کنید.

وقتی وضعیت Gateway مالکان SecretRef را در حالت تخریب‌شده گزارش می‌کند، doctor هشدار افت عملکرد زمان اجرای Secret را همراه با همه مالکان سرد یا منقضی، مسیر پیکربندی تحت تأثیر، دلیل پوشانده‌شده و فرمان تلاش مجدد openclaw secrets reload نمایش می‌دهد.

وقتی رویدادهای ورودی کانال به صف نامه‌های تحویل‌نشده فرستاده می‌شوند، doctor حساب هر کانال تحت تأثیر را نام می‌برد و برای بازرسی و بازیابی به openclaw channels dead-letters list ارجاع می‌دهد.

مرتبط:

• عیب‌یابی: عیب‌یابی
• ممیزی امنیتی: امنیت

حالت‌ها

Doctor پنج حالت دارد:

وقتی خودکارسازی به نتیجه‌ای پایدار نیاز دارد، --lint را ترجیح دهید. وقتی اپراتور انسانی می‌خواهد doctor پیکربندی یا وضعیت را ویرایش کند، --fix را ترجیح دهید.

مثال‌ها

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --jsonopenclaw doctor --state-sqlite compactopenclaw doctor --state-sqlite compact --jsonopenclaw doctor --session-sqlite inspect --session-sqlite-all-agentsopenclaw doctor --session-sqlite dry-run --session-sqlite-agent main --jsonopenclaw doctor --session-sqlite import --session-sqlite-all-agentsopenclaw doctor --session-sqlite validate --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite compact --session-sqlite-all-agentsopenclaw doctor --session-sqlite recover --github-issueopenclaw doctor --session-sqlite restore --session-sqlite-all-agents

برای مجوزهای مختص هر کانال، به‌جای doctor از کاوشگرهای کانال استفاده کنید:

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

channels capabilities مجوزهای مؤثر ربات را برای یک مقصد کانال مشخص گزارش می‌کند. channels status --probe همه کانال‌های پیکربندی‌شده و مقصدهای اتصال خودکار صوتی را ممیزی می‌کند.

گزینه‌ها

--severity-min، --all، --only و --skip فقط همراه با --lint پذیرفته می‌شوند؛ --json همراه با --lint، --post-upgrade، --state-sqlite و --session-sqlite پذیرفته می‌شود.

حالت Lint

openclaw doctor --lint فقط‌خواندنی است: بدون درخواست تأیید، بدون تعمیر و بدون بازنویسی پیکربندی/وضعیت.

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

خروجی انسانی فشرده است:

doctor --lint: 6 بررسی اجرا شد، 1 یافته وجود دارد  [warning] core/doctor/gateway-config gateway.mode - gateway.mode تنظیم نشده است؛ شروع Gateway مسدود خواهد شد.    راه‌حل: `openclaw configure` را اجرا و حالت Gateway را تنظیم کنید (local/remote)، یا `openclaw config set gateway.mode local` را اجرا کنید.

خروجی JSON رابط اسکریپت‌نویسی است:

{  "ok": false,  "checksRun": 5,  "checksSkipped": 0,  "findings": [    {      "checkId": "core/doctor/gateway-config",      "severity": "warning",      "message": "gateway.mode تنظیم نشده است؛ شروع Gateway مسدود خواهد شد.",      "path": "gateway.mode",      "fixHint": "`openclaw configure` را اجرا و حالت Gateway را تنظیم کنید (local/remote)، یا `openclaw config set gateway.mode local` را اجرا کنید."    }  ]}

کدهای خروج:

--severity-min هم یافته‌هایی را که نمایش داده می‌شوند و هم آستانه خروج را کنترل می‌کند: حتی اگر یافته‌های info/warning با شدت پایین‌تر وجود داشته باشند، openclaw doctor --lint --severity-min error می‌تواند هیچ‌چیز نمایش ندهد و با کد 0 خارج شود.

--all تعیین می‌کند پیش از پالایش شدت کدام بررسی‌ها انتخاب شوند. اجرای پیش‌فرض Lint بررسی‌های عمیق، تاریخی یا بررسی‌هایی را که احتمال بیشتری دارد بقایای قدیمی قابل تعمیر را نشان دهند، کنار می‌گذارد؛ برای فهرست کامل از --all استفاده کنید. --only <id> دقیق‌ترین انتخاب‌گر است و می‌تواند هر بررسی ثبت‌شده را براساس شناسه اجرا کند.

core/doctor/local-audio-acceleration فرمان محلی STT انتخاب‌شده به‌صورت خودکار، شواهد مجزای backendهای دارای قابلیت/درخواست‌شده/مشاهده‌شده و ترتیب fallback را بدون بارگذاری مدل گفتار گزارش می‌کند. این گزینه یک یافته اطلاعاتی منتشر می‌کند، بنابراین برای نمایش آن --severity-min info را اضافه کنید.

بررسی‌های سلامت ساخت‌یافته

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

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

detect() نیروی محرک doctor --lint است. repair() اختیاری است و فقط تحت doctor --fix / doctor --repair اجرا می‌شود. بررسی‌هایی که هنوز به این ساختار مهاجرت نکرده‌اند، همچنان از جریان قدیمی مشارکت doctor استفاده می‌کنند.

زمینه‌های تعمیر می‌توانند درخواست‌های dryRun/diff را حمل کنند؛ نتایج تعمیر می‌توانند diffs ساختاریافته (ویرایش‌های پیکربندی/فایل) و effects (اثرات جانبی سرویس، فرایند، بسته، وضعیت یا موارد دیگر) را بازگردانند، بنابراین بررسی‌های تبدیل‌شده می‌توانند به‌سمت doctor --fix --dry-run گسترش یابند، بدون آنکه برنامه‌ریزی تغییرات به detect() منتقل شود.

repair() مقدار status: "repaired" | "skipped" | "failed" را گزارش می‌کند (حذف وضعیت به‌معنای repaired است). وقتی تعمیر مقدار skipped یا failed را بازمی‌گرداند، Doctor دلیل را گزارش می‌کند و اعتبارسنجی آن بررسی را نادیده می‌گیرد. پس از یک تعمیر موفق، Doctor مقدار detect() را با دامنه محدود به یافته‌های تعمیرشده دوباره اجرا می‌کند؛ اگر یافته همچنان وجود داشته باشد، Doctor به‌جای کامل تلقی‌کردن تغییر، هشدار تعمیر گزارش می‌کند.

یک یافته شامل موارد زیر است:

بررسی‌های نوسازی‌شده Doctor در هسته، به مشارکت مرتب‌شده Doctor که مالک رفتار انسانی doctor / doctor --fix آن‌هاست متصل می‌مانند. رجیستری مشترک و ساختاریافته سلامت، نقطه توسعه است: بررسی‌های همراه و متکی به Plugin پس از بررسی‌های Doctor هسته اجرا می‌شوند، به‌محض آنکه بسته مالکشان آن‌ها را در مسیر فرمان فعال ثبت کند. openclaw/plugin-sdk/health همین قرارداد را برای نویسندگان Plugin ارائه می‌کند.

انتخاب بررسی

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

--only و --skip شناسه‌های کامل بررسی را می‌پذیرند و می‌توان آن‌ها را تکرار کرد. اگر شناسه --only ثبت نشده باشد، هیچ بررسی‌ای برای آن شناسه اجرا نمی‌شود؛ برای تأیید اینکه یک گیت متمرکز بررسی‌های مورد انتظار را انتخاب می‌کند، از checksRun/checksSkipped در خروجی استفاده کنید.

حالت پس از ارتقا

openclaw doctor --post-upgrade کاوش‌های سازگاری Plugin را برای زنجیره‌سازی پس از ساخت یا ارتقا اجرا می‌کند. یافته‌ها به stdout می‌روند؛ اگر هر یافته‌ای دارای level: "error" باشد، کد خروج 1 است. برای یک پوشش ماشین‌خوان ({ probesRun, findings }) که برای CI، Skill جامعه fork-upgrade و دیگر ابزارهای آزمون دود پس از ارتقا مناسب است، --json را اضافه کنید. اگر نمایه Plugin نصب‌شده وجود نداشته باشد یا بدشکل باشد، حالت JSON همچنان پوشش را با یک یافته خطای plugin.index_unavailable منتشر می‌کند.

راه‌اندازی ایمیج کانتینر، استثنای جریان معمول «اجرای Doctor پس از به‌روزرسانی» است. هنگامی که openclaw gateway run روی نسخه جدیدی از OpenClaw شروع می‌شود، پیش از اعلام آمادگی، تعمیرات امن وضعیت و Plugin را اجرا می‌کند. اگر تعمیر نتواند با ایمنی کامل شود، راه‌اندازی خارج می‌شود و از شما می‌خواهد پیش از راه‌اندازی مجدد عادی کانتینر، همان ایمیج را یک‌بار با openclaw doctor --fix در برابر همان وضعیت/پیکربندی متصل‌شده اجرا کنید.

مهاجرت وضعیت قدیمی

openclaw doctor --fix تنها مالک مهاجرت‌های پایدار از فایل به SQLite است. هر منبع شناخته‌شده را اعتبارسنجی و تصاحب می‌کند، ردیف‌های استاندارد را می‌نویسد و تأیید می‌کند، رسید مهاجرت را ثبت می‌کند و سپس منبع بازنشسته را حذف می‌کند. کد زمان اجرا واردکردن تنبل یا خواندن جایگزین انجام نمی‌دهد.

این شامل فایل‌های بازنشسته OAuth مربوط به MCP در <state-dir>/mcp-oauth/*.json نیز می‌شود. پیش از تعمیر، Gateway را متوقف کنید. Doctor اعتبارنامه‌های معتبر را به <state-dir>/state/openclaw.sqlite وارد می‌کند، هنگامی که هر دو مخزن وجود دارند نشست استاندارد SQLite موجود را حفظ می‌کند، مقدار منسوخ و ذخیره‌شده OAuth یعنی state را حذف می‌کند و از رسید خود برای جلوگیری از آن استفاده می‌کند که یک فایل کهنه بازسازی‌شده، اعتبارنامه‌های خارج‌شده از حساب را دوباره فعال کند. فایل‌های جانبی بازنشسته .lock به‌صورت بسته شکست می‌خورند: اگر Doctor مالک کهنه‌ای را گزارش کرد، تأیید کنید هیچ فرایند قدیمی‌تر OpenClaw در حال اجرا نیست، آن فایل جانبی را حذف کنید و Doctor را دوباره اجرا کنید.

Compaction پایگاه SQLite وضعیت مشترک

برای نسخه‌بندی طرح‌واره، بررسی‌های یکپارچگی و بازیابی پس از تنزل نسخه، به طرح‌واره‌های پایگاه داده مراجعه کنید.

openclaw doctor --state-sqlite compact نگه‌داری آفلاین صریح برای پایگاه داده استاندارد وضعیت مشترک در <state-dir>/state/openclaw.sqlite است. این فرمان مسیر دلخواه پایگاه داده را نمی‌پذیرد، هرگز توسط عملیات عادی Gateway فراخوانی نمی‌شود و بخشی از openclaw doctor --fix نیست. فرمان همان قفل مالکیت وضعیت راه‌اندازی Gateway را می‌گیرد و آن را در تمام مراحل اعتبارسنجی، ایجاد نقطه بررسی، VACUUM و بررسی‌های نهایی یکپارچگی نگه می‌دارد. هنگامی که یک Gateway یا فرمان نگه‌داری SQLite دیگری مالک آن قفل باشد، از اجرا خودداری می‌کند. قفل وضعیت هنگامی که OPENCLAW_ALLOW_MULTI_GATEWAY=1 نمونه منفرد Gateway مربوط به هر پیکربندی را نادیده می‌گیرد نیز فعال می‌ماند؛ بنابراین برای اینکه نگه‌داری بتواند سرویس Gateway را تشخیص دهد، پوسته اپراتور نیازی ندارد محیط آن را به ارث ببرد.

ابتدا Gateway را متوقف و یک پشتیبان تأییدشده ایجاد کنید:

openclaw gateway stopopenclaw backup create --verifyopenclaw doctor --state-sqlite compact --jsonopenclaw gateway start

فرمان:

1. به یک فایل عادی در مسیر استاندارد وضعیت مشترک نیاز دارد. نبود پایگاه داده به‌صورت skipped گزارش می‌شود و با موفقیت خارج می‌شود.
2. نسخه فعلی و پشتیبانی‌شده طرح‌واره و schema_meta.role = "global" را پیش از ایجاد نقطه بررسی یا تغییر فایل اعتبارسنجی می‌کند.
3. به یک wal_checkpoint(TRUNCATE) غیرفعال نیاز دارد. اگر نقطه بررسی مشغول است، هر فرایند باقی‌مانده OpenClaw را متوقف و دوباره تلاش کنید.
4. مقدار auto_vacuum را روی INCREMENTAL تنظیم می‌کند، یک VACUUM کامل اجرا می‌کند و دوباره نقطه بررسی ایجاد می‌کند.
5. مقادیر quick_check، integrity_check و foreign_key_check را اجرا می‌کند و سپس مجوزهای فقط‌مالک را دوباره روی پایگاه داده و فایل‌های جانبی SQLite اعمال می‌کند.

خروجی JSON اندازه‌های پایگاه داده و WAL، صفحه‌های فهرست آزاد، اندازه صفحه و مقدار auto_vacuum را پیش و پس از Compaction، همراه با بایت‌های بازیابی‌شده و نتایج quick_check و integrity_check گزارش می‌کند. foreign_key_check به‌صورت بسته اعمال می‌شود و فیلد موفقیت جداگانه‌ای ندارد. SQLite مقدار auto_vacuum را برای هیچ‌کدام به‌صورت 0، برای کامل به‌صورت 1 و برای افزایشی به‌صورت 2 گزارش می‌کند.

هنگامی که طرح‌واره قدیمی، جدیدتر از بیلد در حال اجرای OpenClaw، یا متعلق به یک پایگاه داده عامل باشد، Compaction بدون تغییر شکست می‌خورد. برای طرح‌واره قدیمی‌تر وضعیت مشترک، ابتدا openclaw doctor --fix را اجرا کنید. برای طرح‌واره جدیدتر، یک پشتیبان سازگار را بازیابی کنید یا OpenClaw را ارتقا دهید.

مهاجرت SQLite نشست

OpenClaw ردیف‌های قدیمی نشست و تاریخچه رونوشت را هنگام راه‌اندازی Gateway و هنگام openclaw doctor --fix به‌طور خودکار به پایگاه داده SQLite هر عامل وارد می‌کند. openclaw doctor --session-sqlite <mode> ابزار متمرکز بازرسی و اعتبارسنجی آن مهاجرت است. ردیف‌های زمان اجرای فعلی نشست در ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite قرار دارند. فایل‌های قدیمی sessions.json منابع مهاجرت هستند. فایل‌های داغ JSONL رونوشت وارد شده و پس از واردکردن موفق از دایرکتوری نشست‌های فعال بایگانی می‌شوند؛ فایل‌های JSONL سطح بایگانی، مصنوعات پشتیبانی باقی می‌مانند، نه جایگزین‌های زمان اجرا.

حالت‌ها:

انتخاب‌گرها:

• پیش‌فرض: مخزن پیکربندی‌شده عامل پیش‌فرض، هنگامی که آن فایل مخزن قدیمی وجود داشته باشد.
• --session-sqlite-agent <id>: یک عامل پیکربندی‌شده.
• --session-sqlite-all-agents: مخزن‌های پیکربندی‌شده عامل به‌علاوه مخزن‌های کشف‌شده عامل.
• --session-sqlite-store <path>: یک مسیر صریح قدیمی sessions.json.

توالی بازرسی دستی:

openclaw doctor --session-sqlite inspect --session-sqlite-all-agentsopenclaw doctor --session-sqlite dry-run --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite import --session-sqlite-all-agentsopenclaw doctor --session-sqlite validate --session-sqlite-all-agents --jsonopenclaw doctor --session-sqlite compact --session-sqlite-all-agentsopenclaw doctor --session-sqlite recover --github-issue

پیش از اجرای import روی نصبی با تاریخچه مهم، از دایرکتوری وضعیت OpenClaw پشتیبان بگیرید. هنگامی که یک ورودی قدیمی انتخاب‌شده در SQLite وجود نداشته باشد، شناسه نشست متفاوت باشد یا تعداد رویدادهای رونوشت متفاوت باشد، validate با کد غیرصفر خارج می‌شود. هنگام استفاده از --session-sqlite-store <path>، بررسی کنید گزارش شامل تعداد هدف مورد انتظار باشد؛ مسیر صریح مخزنی که وجود ندارد هیچ هدفی را انتخاب نمی‌کند.

حذف‌های SQLite ابتدا صفحه‌ها را درون پایگاه داده آزاد می‌کنند؛ لزوماً فایل پایگاه داده را فوراً کوچک نمی‌کنند. پس از حذف یا بایگانی رونوشت‌های بزرگ، openclaw doctor --session-sqlite compact --session-sqlite-all-agents را اجرا کنید تا فایل‌های WAL نقطه‌گذاری شوند، VACUUM اجرا شود و اندازه‌های پیش/پس پایگاه داده و WAL گزارش شوند. Compaction به یک فایل عادی با طرح‌واره فعلی عامل، فراداده مالک پایدار عامل انتخاب‌شده و نبود دسته باز در فرایند Doctor نیاز دارد. حالت‌های مخرب import، compact، recover و restore همان قفل مالکیت وضعیت راه‌اندازی Gateway را در تمام عملیات خود نگه می‌دارند؛ inspect، dry-run و validate فقط‌خواندنی می‌مانند و آن را نمی‌گیرند. ابتدا Gateway را متوقف کنید. حالت‌های مخرب به‌جای رقابت با نوشتن‌های زنده یا فرمان نگه‌داری دیگری شکست می‌خورند. هدف مخرب --session-sqlite-store باید درون دایرکتوری وضعیت فعال باشد؛ پیش از نگه‌داری نصب دیگری، OPENCLAW_STATE_DIR را روی دایرکتوری وضعیت مالک مخزن تنظیم کنید. اهداف موجود دارای پیوند سخت رد می‌شوند، زیرا مسیر دیگری می‌تواند همان آی‌نود پایگاه داده را بیرون از دایرکتوری وضعیت قفل‌شده به‌اشتراک بگذارد. همان بررسی‌های مالکیت، فایل‌های جانبی WAL، حافظه اشتراکی و ژورنال بازگردانی SQLite را نیز پوشش می‌دهند.

هر واردکردن پیش از انتقال مصنوعات رونوشت به بایگانی، یک مانیفست در ~/.openclaw/session-sqlite-migration-runs/ می‌نویسد. اگر راه‌اندازی پس از انتقال مصنوعات، مهاجرت ناموفق SQLite نشست را گزارش کرد، بازیابی را اجرا کنید:

openclaw doctor --session-sqlite recover --github-issue

بازیابی، جدیدترین مانیفست مهاجرت ناموفق را انتخاب می‌کند، فقط مصنوعات بایگانی‌شدهٔ مانیفست را بازمی‌گرداند، اهداف متأثر را اعتبارسنجی می‌کند، گزارش‌های پالایش‌شدهٔ .failure.md و .failure.json را به‌روزرسانی می‌کند و بدنهٔ یک مسئلهٔ GitHub را آماده می‌کند که از محتوای رونوشت، محیط خام، اسرار و پیکربندی نامحدود اجتناب می‌کند. وقتی هیچ مانیفست مهاجرت ناموفقی وجود ندارد، اما پایگاه دادهٔ SQLite عامل انتخاب‌شده خراب است، پایگاه داده نیست، یا فایل‌های جانبی ژورنال بدون پایگاه دادهٔ اصلی دارد، بازیابی مجموعهٔ کامل فایل‌ها را در یک پوشهٔ موقت بازرسی کپی می‌کند. SQLite می‌تواند پیش از اجرای quick_check، integrity_check و foreign_key_check یک ژورنال داغ معتبر را در آن کپی دورریختنی بازگردانی کند، درحالی‌که فایل‌های اصلی جرم‌شناختی دست‌نخورده باقی می‌مانند. بررسی‌های یکپارچگی ناموفق یا فایل‌های جانبی یتیم، فایل‌های DB، WAL، SHM و ژورنال بازگردانی را با تغییر نام کل مجموعهٔ کشف‌شده با یک پسوند .corrupt-<timestamp> حفظ می‌کنند. در صورت وقوع خطای تغییر نام، فایل‌هایی که پیش‌تر جابه‌جا شده‌اند قبل از گزارش خطا به جای خود بازگردانده می‌شوند تا مجموعه‌فایل قابل‌بازیابی بی‌سروصدا تقسیم نشود. پیش از بازیابی، Gateway را متوقف کنید؛ کپی یا تغییر نام مجموعه‌فایل SQLite که فعالانه در حال تغییر است، ناامن است و در سیستم‌عامل‌های مختلف رفتار متفاوتی دارد. با --github-issue --yes، doctor از GitHub CLI برای ایجاد مسئله در openclaw/openclaw استفاده می‌کند؛ بدون تأیید، گزارش پشتیبانی محلی را می‌نویسد و یک URL ازپیش‌پرشدهٔ مسئله را چاپ می‌کند.

restore همچنان عملیات بازگردانی سطح پایین‌تر است. این عملیات از رکوردهای sourcePath -> archivePath مانیفست استفاده می‌کند، مصنوعات بایگانی‌شده را فقط زمانی به جای قبلی بازمی‌گرداند که مسیر اصلی وجود نداشته باشد، وقتی هر دو مسیر وجود دارند تعارض‌ها را گزارش می‌کند و پایگاه دادهٔ SQLite را در جای خود باقی می‌گذارد.

تنزل نسخه پس از مهاجرت SQLite نشست

پیش از راه‌اندازی نسخهٔ قدیمی‌تر و فایل‌محور OpenClaw، مصنوعات بایگانی‌شدهٔ رونوشت قدیمی را بازیابی کنید:

openclaw doctor --session-sqlite restore --session-sqlite-all-agents

نسخه‌های قدیمی‌تر ورودی‌های sessions.json و مسیرهای sessionFile ثبت‌شده در آن ورودی‌ها را می‌خوانند. پس از مهاجرت SQLite، واردسازی‌های موفق رونوشت‌های فعال JSONL را به session-sqlite-import-archive/ منتقل می‌کنند؛ بنابراین، زمان اجرای قدیمی‌تر نمی‌تواند آن تاریخچه را ببیند تا زمانی که بازیابی، مصنوعات ثبت‌شده در مانیفست را به مسیرهای اصلی‌شان بازگرداند.

بازیابی، داده‌های SQLite را حذف نمی‌کند. نشست‌هایی که پس از تغییر به SQLite ایجاد شده‌اند فقط در SQLite وجود دارند و در زمان اجرای قدیمی‌تر ظاهر نخواهند شد. اگر بعداً دوباره ارتقا دادید، توالی عادی اعتبارسنجی مهاجرت بالا را اجرا کنید تا OpenClaw بتواند پیش از واردسازی، مصنوعات قدیمی بازیابی‌شده را با ردیف‌های SQLite مقایسه کند.

یادداشت‌ها

• در حالت Nix (OPENCLAW_NIX_MODE=1)، بررسی‌های فقط‌خواندنی doctor همچنان کار می‌کنند، اما doctor --fix، doctor --repair، doctor --yes و doctor --generate-gateway-token غیرفعال‌اند، زیرا openclaw.json تغییرناپذیر است. در عوض، منبع Nix این نصب را ویرایش کنید؛ برای nix-openclaw، از شروع سریع مبتنی بر عامل استفاده کنید.
• درخواست‌های تعاملی (رفع مشکلات keychain/OAuth و غیره) فقط زمانی اجرا می‌شوند که stdin یک TTY باشد و --non-interactive تنظیم نشده باشد. اجراهای بدون رابط (cron، Telegram، بدون ترمینال) درخواست‌ها را نادیده می‌گیرند.
• اجراهای غیرتعاملی doctor بارگذاری پیش‌دستانه Plugin را نادیده می‌گیرند تا بررسی‌های سلامت بدون رابط سریع بمانند. نشست‌های تعاملی همچنان سطوح Plugin موردنیاز جریان قدیمی سلامت/ترمیم را بارگذاری می‌کنند.
• --lint از --non-interactive سخت‌گیرانه‌تر است: همیشه فقط‌خواندنی است، هرگز درخواست تعاملی نمایش نمی‌دهد و هرگز مهاجرت‌های امن را اعمال نمی‌کند. وقتی می‌خواهید doctor تغییراتی ایجاد کند، از doctor --fix یا doctor --repair استفاده کنید.
• Doctor هنگام بررسی رازها، به‌طور پیش‌فرض SecretRefهای exec را اجرا نمی‌کند. فقط زمانی از --allow-exec (با یا بدون --lint) استفاده کنید که عمداً می‌خواهید doctor آن حل‌کننده‌های راز پیکربندی‌شده را اجرا کند.
• هرگونه نوشتن پیکربندی (از جمله ترمیم --fix) یک نسخهٔ پشتیبان را به ~/.openclaw/openclaw.json.bak می‌چرخاند (با حلقهٔ شماره‌گذاری‌شدهٔ .bak.1...bak.4). --fix همچنین کلیدهای ناشناختهٔ پیکربندی را که اعتبارسنجی شِما گزارش می‌کند حذف کرده و هر حذف را فهرست می‌کند؛ هنگام انجام به‌روزرسانی از این کار صرف‌نظر می‌کند تا وضعیت ارتقای نیمه‌نوشته پیش از پایان مهاجرت آن حذف نشود.
• اگر openclaw.json قابل تجزیه نباشد و هیچ پیکربندی سالمِ شناخته‌شدهٔ اخیر بازیابی نشود، doctor --fix نسخهٔ اصلی را با نام openclaw.json.clobbered.<timestamp> نگه می‌دارد، فایل فعلی را بدون تغییر باقی می‌گذارد و به‌جای نوشتن یک جایگزین ناقص، با خطا خارج می‌شود.
• وقتی ناظر دیگری چرخهٔ عمر Gateway را مدیریت می‌کند، OPENCLAW_SERVICE_REPAIR_POLICY=external را تنظیم کنید. Doctor همچنان سلامت Gateway/سرویس را گزارش می‌کند و ترمیم‌های غیرسرویسی را اعمال می‌کند، اما نصب/شروع/راه‌اندازی مجدد/bootstrap سرویس و پاک‌سازی سرویس قدیمی را نادیده می‌گیرد.
• Doctor محدودیت heap اعمال‌شدهٔ Gateway مدیریت‌شده و روش استخراج تطبیقی استفاده‌شده برای محدودیت حافظهٔ میزبان یا کانتینر فعلی را گزارش می‌کند. برای دریافت همین گزارش خارج از مرحلهٔ ترمیم، از openclaw gateway status استفاده کنید.
• در Linux، doctor واحدهای systemd اضافی و غیرفعال شبیه Gateway را نادیده می‌گیرد و هنگام ترمیم، فرادادهٔ فرمان/نقطهٔ ورود سرویس Gateway درحال اجرای systemd را بازنویسی نمی‌کند. ابتدا سرویس را متوقف کنید، یا برای جایگزینی راه‌انداز فعال از openclaw gateway install --force استفاده کنید.
• doctor --fix --non-interactive تعریف‌های مفقود یا قدیمی سرویس Gateway را گزارش می‌کند، اما خارج از حالت ترمیم به‌روزرسانی آن‌ها را نصب یا بازنویسی نمی‌کند. برای سرویس مفقود، openclaw gateway install را اجرا کنید، یا برای جایگزینی راه‌انداز از openclaw gateway install --force استفاده کنید.
• بررسی‌های یکپارچگی وضعیت، فایل‌های رونوشت یتیم را در پوشهٔ نشست‌ها شناسایی می‌کنند. بایگانی آن‌ها به‌صورت .deleted.<timestamp> به تأیید تعاملی نیاز دارد؛ --fix، --yes و اجراهای بدون رابط آن‌ها را در جای خود باقی می‌گذارند.
• Doctor مسیر ~/.openclaw/cron/jobs.json (یا cron.store) را برای ساختارهای قدیمی کارهای cron اسکن می‌کند و پیش از واردکردن ردیف‌های معیار به SQLite، آن‌ها را بازنویسی می‌کند.
• Doctor کارهای cron دارای جایگزینی صریح payload.model را همراه با تعدادهای فضای نام ارائه‌دهنده و مغایرت‌ها با agents.defaults.model گزارش می‌کند تا کارهای زمان‌بندی‌شده‌ای که مدل پیش‌فرض را به ارث نمی‌برند، هنگام بررسی مشکلات احراز هویت یا صورت‌حساب قابل مشاهده باشند.
• Doctor کارهای cron را که همچنان درحال اجرا علامت‌گذاری شده‌اند (state.runningAtMs) گزارش می‌کند؛ این وضعیت می‌تواند باعث شود openclaw cron list آن‌ها را به‌صورت running نمایش دهد. این بررسی فقط‌خواندنی است: اگر درحال‌حاضر هیچ Gateway کار علامت‌گذاری‌شده‌ای را اجرا نمی‌کند، راه‌اندازی بعدی سرویس cron اجرای قطع‌شده را ثبت و نشانگر را پاک می‌کند.
• در Linux، doctor هنگامی هشدار می‌دهد که crontab کاربر همچنان ~/.openclaw/bin/ensure-whatsapp.sh قدیمی و نگهداری‌نشده را اجرا می‌کند؛ این مورد وقتی cron فاقد محیط گذرگاه کاربر systemd باشد، ممکن است Gateway inactive را نادرست گزارش کند.
• وقتی WhatsApp فعال است، doctor وجود حلقهٔ رویداد تضعیف‌شدهٔ Gateway را در حالی بررسی می‌کند که کلاینت‌های محلی openclaw-tui همچنان درحال اجرا هستند. doctor --fix فقط کلاینت‌های محلی TUI تأییدشده را متوقف می‌کند تا پاسخ‌های WhatsApp پشت حلقه‌های بازآوری قدیمی TUI در صف نمانند.
• وقتی متغیرهای محیطی پراکسی HTTP(S) وجود دارند اما tools.web.fetch.useTrustedEnvProxy غیرفعال است، doctor توضیح می‌دهد که web_fetch همچنان از مسیریابی مستقیم استفاده می‌کند، یک کاوش کوتاه اتصال مستقیم TLS اجرا می‌کند و گزینهٔ پذیرش صریح را نام می‌برد. هرگز اعتماد به پراکسی را به‌طور خودکار فعال نمی‌کند.
• Doctor ارجاع‌های قدیمی مدل codex/* و openai-codex/* را در مدل‌های اصلی، جایگزین‌ها، فهرست‌های مجاز مدل، مدل‌های تولید تصویر/ویدئو، جایگزینی‌های heartbeat/زیرعامل/compaction، قلاب‌ها، جایگزینی مدل کانال، محموله‌های cron و پین‌های قدیمی مسیر نشست/رونوشت، به ارجاع‌های معیار openai/* بازنویسی می‌کند. --fix همچنین در صورت ایمن‌بودن، پیکربندی قدیمی models.providers.codex و models.providers.openai-codex را ادغام می‌کند، پروفایل‌های قدیمی احراز هویت openai-codex:* و ورودی‌های auth.order.openai-codex را به openai:* مهاجرت می‌دهد، قصد Codex را به ورودی‌های agentRuntime.id: "codex" در محدودهٔ ارائه‌دهنده/مدل منتقل می‌کند، پین‌های قدیمی زمان اجرای کل عامل/نشست را حذف می‌کند و ارجاع‌های ترمیم‌شدهٔ عامل OpenAI را به‌جای احراز هویت مستقیم با کلید API ‏OpenAI، روی مسیریابی احراز هویت Codex نگه می‌دارد.
• Doctor فهرست‌های غیرخالی auth.order.<provider> را گزارش می‌کند که همهٔ پروفایل‌های ارجاع‌شدهٔ آن‌ها از بین رفته‌اند، اما اعتبارنامه‌های سازگار ذخیره‌شده وجود دارند. doctor --fix فقط همان جایگزینی‌های قدیمی را حذف می‌کند و انتخاب خودکار اعتبارنامه به‌ازای هر عامل را بازمی‌گرداند؛ ترتیب‌های صریحاً خالی، فهرست‌های بخشی فعال و ترتیب‌های فاقد اعتبارنامهٔ ذخیره‌شدهٔ سازگار بدون تغییر می‌مانند. اگر مخزن فعال احراز هویت SQLite ناخوانا یا بدساخت باشد، doctor توضیح می‌دهد چرا این ترمیم را نادیده گرفته است. اگر حالت بازخوانی پیکربندی Gateway درحال اجرا، نوشتن را خودکار اعمال نمی‌کند، پیش از بررسی دوبارهٔ وضعیت احراز هویت آن را راه‌اندازی مجدد کنید.
• Doctor وضعیت قدیمی آماده‌سازی وابستگی Plugin از نسخه‌های قدیمی‌تر OpenClaw را پاک می‌کند و بستهٔ openclaw میزبان را برای Pluginهای npm مدیریت‌شده‌ای که آن را به‌عنوان وابستگی همتا اعلام می‌کنند، دوباره پیوند می‌دهد. همچنین Pluginهای دانلودشدنی مفقودی را که پیکربندی به آن‌ها ارجاع می‌دهد ترمیم می‌کند (plugins.entries، کانال‌های پیکربندی‌شده، تنظیمات ارائه‌دهنده/جست‌وجوی پیکربندی‌شده، زمان‌های اجرای عامل پیکربندی‌شده). هنگام به‌روزرسانی بسته‌ها، doctor ترمیم Plugin توسط مدیر بسته را تا تکمیل تعویض بسته نادیده می‌گیرد؛ اگر Plugin پیکربندی‌شده‌ای همچنان به بازیابی نیاز داشت، پس از آن openclaw doctor --fix را دوباره اجرا کنید. اگر دانلود ناموفق باشد، doctor خطای نصب را گزارش می‌کند و ورودی Plugin پیکربندی‌شده را برای تلاش ترمیم بعدی نگه می‌دارد.
• وقتی کشف Plugin سالم است، doctor پیکربندی قدیمی Plugin را با حذف شناسه‌های Plugin مفقود از plugins.allow/plugins.deny/plugins.entries، به‌همراه پیکربندی معلق کانال، هدف‌های heartbeat و جایگزینی‌های مدل کانال متناظر ترمیم می‌کند.
• Doctor پیکربندی نامعتبر Plugin را با غیرفعال‌کردن ورودی plugins.entries.<id> متأثر و حذف محمولهٔ نامعتبر config آن قرنطینه می‌کند. راه‌اندازی Gateway از قبل فقط همان Plugin معیوب را نادیده می‌گیرد تا سایر Pluginها و کانال‌ها همچنان اجرا شوند.
• Doctor گزینهٔ بازنشستهٔ plugins.entries.codex.config.codexDynamicToolsProfile را حذف می‌کند؛ app-server ‏Codex همیشه ابزارهای فضای کاری بومی Codex را بومی نگه می‌دارد.
• Doctor پیکربندی تخت و قدیمی Talk (talk.voiceId، talk.modelId و موارد مشابه) را به‌طور خودکار به talk.provider + talk.providers.<provider> مهاجرت می‌دهد. اجراهای تکراری doctor --fix دیگر وقتی تنها تفاوت، ترتیب کلیدهای شیء است، عادی‌سازی Talk را گزارش/اعمال نمی‌کنند.
• Doctor شامل بررسی آمادگی جست‌وجوی حافظه است و در صورت مفقودبودن اعتبارنامه‌های تعبیه‌سازی، می‌تواند openclaw configure --section model را توصیه کند.
• Doctor هنگامی هشدار می‌دهد که هیچ مالک فرمانی پیکربندی نشده باشد. مالک فرمان، حساب اپراتور انسانی است که اجازه دارد فرمان‌های مختص مالک را اجرا و اقدام‌های خطرناک را تأیید کند. جفت‌سازی پیام خصوصی فقط به شخص اجازه می‌دهد با ربات گفت‌وگو کند؛ اگر پیش از وجود bootstrap نخستین مالک، فرستنده‌ای را تأیید کرده‌اید، commands.ownerAllowFrom را صریحاً تنظیم کنید.
• Doctor وقتی عامل‌های حالت Codex پیکربندی شده‌اند و دارایی‌های شخصی Codex CLI در خانهٔ Codex اپراتور وجود دارند، یک یادداشت اطلاعاتی گزارش می‌کند. راه‌اندازی‌های محلی app-server ‏Codex از خانه‌های مجزای هر عامل استفاده می‌کنند؛ در صورت نیاز ابتدا Plugin ‏Codex را نصب کنید، سپس برای فهرست‌برداری از دارایی‌هایی که باید آگاهانه ارتقا یابند، از openclaw migrate plan codex استفاده کنید.
• Doctor وقتی Skills مجاز برای عامل پیش‌فرض در محیط زمان اجرای فعلی در دسترس نیستند (فقدان فایل‌های اجرایی، متغیرهای محیطی، پیکربندی یا الزامات سیستم‌عامل)، هشدار می‌دهد. doctor --fix می‌تواند آن Skills در دسترس‌نبودنی را با skills.entries.<skill>.enabled=false غیرفعال کند؛ اگر می‌خواهید Skill فعال بماند، به‌جای آن الزام مفقود را نصب/پیکربندی کنید.
• اگر حالت sandbox فعال باشد اما Docker در دسترس نباشد، doctor هشداری با اهمیت بالا و راهکار اصلاح (install Docker یا openclaw config set agents.defaults.sandbox.mode off) گزارش می‌کند.
• اگر فایل‌های قدیمی رجیستری sandbox یا پوشه‌های shard وجود داشته باشند (~/.openclaw/sandbox/containers.json، ~/.openclaw/sandbox/browsers.json، ~/.openclaw/sandbox/containers/ یا ~/.openclaw/sandbox/browsers/)، doctor آن‌ها را گزارش می‌کند؛ --fix ورودی‌های معتبر را به SQLite مهاجرت داده و فایل‌های قدیمی نامعتبر را قرنطینه می‌کند.
• اگر gateway.auth.token/gateway.auth.password توسط SecretRef مدیریت شوند و در مسیر فرمان فعلی در دسترس نباشند، doctor هشداری فقط‌خواندنی گزارش می‌کند و اعتبارنامه‌های جایگزین متن ساده نمی‌نویسد. برای SecretRefهای مبتنی بر exec، doctor اجرا را نادیده می‌گیرد، مگر اینکه --allow-exec وجود داشته باشد.
• اگر بازرسی SecretRef کانال در مسیر اصلاح ناموفق باشد، doctor به‌جای خروج زودهنگام، ادامه می‌دهد و هشداری گزارش می‌کند.
• پس از مهاجرت پوشهٔ وضعیت، doctor هنگامی هشدار می‌دهد که حساب‌های پیش‌فرض فعال Telegram یا Discord به جایگزین محیطی وابسته‌اند و TELEGRAM_BOT_TOKEN یا DISCORD_BOT_TOKEN برای فرایند doctor در دسترس نیست.
• حل خودکار نام کاربری allowFrom در Telegram (doctor --fix) به توکن قابل‌حل Telegram در مسیر فرمان فعلی نیاز دارد. اگر بازرسی توکن در دسترس نباشد، doctor هشداری گزارش می‌کند و حل خودکار را برای آن مرحله نادیده می‌گیرد.

macOS: جایگزینی‌های محیطی launchctl

اگر قبلاً launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (یا ...PASSWORD) را اجرا کرده‌اید، آن مقدار فایل پیکربندی شما را نادیده می‌گیرد و می‌تواند باعث خطاهای مداوم «غیرمجاز» شود.

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

مرتبط

• مرجع CLI
• Doctor ‏Gateway