خروجی عیب‌یابی

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

تا زمانی که بسته‌های تشخیصی را بازبینی نکرده‌اید، با آن‌ها مثل اسرار برخورد کنید. این بسته‌ها طوری طراحی شده‌اند که payloadها و اطلاعات احراز هویت را حذف یا ویرایش کنند، اما همچنان لاگ‌های محلی Gateway و وضعیت runtime در سطح میزبان را خلاصه می‌کنند.

شروع سریع

openclaw gateway diagnostics export

این دستور مسیر فایل zip نوشته‌شده را چاپ می‌کند. برای انتخاب مسیر:

openclaw gateway diagnostics export --output openclaw-diagnostics.zip

برای خودکارسازی:

openclaw gateway diagnostics export --json

دستور چت

مالکان می‌توانند در چت از /diagnostics [note] برای درخواست خروجی محلی Gateway استفاده کنند. وقتی خطا در یک گفت‌وگوی واقعی رخ داده و یک گزارش قابل کپی‌کردن برای پشتیبانی می‌خواهید، از این استفاده کنید:

1. در گفت‌وگویی که مشکل را در آن دیدید، /diagnostics را ارسال کنید. اگر کمک می‌کند، یک یادداشت کوتاه اضافه کنید، برای مثال /diagnostics bad tool choice.
2. OpenClaw مقدمه تشخیص را می‌فرستد و یک تأیید صریح اجرای دستور درخواست می‌کند. این تأیید openclaw gateway diagnostics export --json را اجرا می‌کند. تشخیص‌ها را از طریق یک قانون اجازه‌دادن به همه تأیید نکنید.
3. پس از تأیید، OpenClaw با گزارشی قابل چسباندن پاسخ می‌دهد که شامل مسیر بسته محلی، خلاصه manifest، نکات حریم خصوصی، و شناسه‌های نشست مرتبط است.

در چت‌های گروهی، مالک همچنان می‌تواند /diagnostics را اجرا کند، اما OpenClaw جزئیات تشخیصی را دوباره در چت مشترک منتشر نمی‌کند. مقدمه، درخواست‌های تأیید، نتیجه خروجی Gateway، و تفکیک نشست/رشته Codex را از طریق مسیر تأیید خصوصی برای مالک ارسال می‌کند. گروه فقط یک اطلاع کوتاه دریافت می‌کند که جریان تشخیصی به‌صورت خصوصی ارسال شده است. اگر OpenClaw نتواند یک مسیر خصوصی مالک پیدا کند، دستور به‌صورت بسته شکست می‌خورد و از مالک می‌خواهد آن را از یک پیام مستقیم اجرا کند.

وقتی نشست فعال OpenClaw از harness بومی OpenAI Codex استفاده می‌کند، همان تأیید اجرای دستور، بارگذاری بازخورد OpenAI را هم برای رشته‌های runtime مربوط به Codex که OpenClaw آن‌ها را می‌شناسد پوشش می‌دهد. این بارگذاری از فایل zip محلی Gateway جداست و فقط برای نشست‌های harness مربوط به Codex ظاهر می‌شود. پیش از تأیید، پیام توضیح می‌دهد که تأیید تشخیص‌ها بازخورد Codex را هم ارسال می‌کند، اما شناسه‌های نشست یا رشته Codex را فهرست نمی‌کند. پس از تأیید، پاسخ چت کانال‌ها، شناسه‌های نشست OpenClaw، شناسه‌های رشته Codex، و دستورهای ادامه محلی را برای رشته‌هایی که به سرورهای OpenAI ارسال شده‌اند فهرست می‌کند. اگر تأیید را رد یا نادیده بگیرید، OpenClaw خروجی را اجرا نمی‌کند، بازخورد Codex را ارسال نمی‌کند، و شناسه‌های Codex را چاپ نمی‌کند.

این کار چرخه رایج اشکال‌زدایی Codex را کوتاه می‌کند: رفتار بد را در Telegram، Discord، یا کانال دیگری ببینید، /diagnostics را اجرا کنید، یک‌بار تأیید کنید، گزارش را با پشتیبانی به اشتراک بگذارید، سپس اگر می‌خواهید رشته بومی Codex را خودتان بررسی کنید، دستور چاپ‌شده codex resume <thread-id> را به‌صورت محلی اجرا کنید. برای آن جریان بررسی، harness مربوط به Codex را ببینید.

خروجی شامل چه چیزهایی است

فایل zip شامل این موارد است:

• summary.md: نمای کلی خوانا برای انسان جهت پشتیبانی.
• diagnostics.json: خلاصه خوانا برای ماشین از پیکربندی، لاگ‌ها، وضعیت، سلامت، و داده‌های پایداری.
• manifest.json: فراداده خروجی و فهرست فایل‌ها.
• شکل پیکربندی پاک‌سازی‌شده و جزئیات غیرمحرمانه پیکربندی.
• خلاصه‌های لاگ پاک‌سازی‌شده و خط‌های لاگ اخیر با ویرایش اطلاعات حساس.
• عکس‌های فوری بهترین‌تلاش از وضعیت و سلامت Gateway.
• stability/latest.json: جدیدترین بسته پایداری ذخیره‌شده، وقتی موجود باشد.

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

مدل حریم خصوصی

تشخیص‌ها طوری طراحی شده‌اند که قابل اشتراک‌گذاری باشند. خروجی داده‌های عملیاتی‌ای را نگه می‌دارد که به اشکال‌زدایی کمک می‌کنند، مانند:

• نام‌های زیرسیستم، شناسه‌های plugin، شناسه‌های provider، شناسه‌های کانال، و حالت‌های پیکربندی‌شده
• کدهای وضعیت، مدت‌زمان‌ها، شمارش بایت‌ها، وضعیت صف، و خوانش‌های حافظه
• فراداده لاگ پاک‌سازی‌شده و پیام‌های عملیاتی با ویرایش اطلاعات حساس
• شکل پیکربندی و تنظیمات غیرمحرمانه ویژگی‌ها

خروجی این موارد را حذف یا ویرایش می‌کند:

• متن چت، promptها، دستورالعمل‌ها، بدنه‌های webhook، و خروجی‌های ابزار
• اطلاعات احراز هویت، کلیدهای API، توکن‌ها، کوکی‌ها، و مقادیر محرمانه
• بدنه‌های خام درخواست یا پاسخ
• شناسه‌های حساب، شناسه‌های پیام، شناسه‌های خام نشست، نام‌های میزبان، و نام‌های کاربری محلی

وقتی یک پیام لاگ شبیه متن کاربر، چت، prompt، یا payload ابزار باشد، خروجی فقط این را نگه می‌دارد که یک پیام حذف شده است و شمارش بایت را ثبت می‌کند.

ضبط‌کننده پایداری

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

همان Heartbeat تشخیصی، وقتی Gateway همچنان در حال اجراست اما حلقه رویداد Node.js یا CPU اشباع به نظر می‌رسد، نمونه‌های زنده‌بودن را ثبت می‌کند. این رویدادهای diagnostic.liveness.warning شامل تأخیر حلقه رویداد، استفاده از حلقه رویداد، نسبت هسته CPU، شمارش نشست‌های فعال/در انتظار/در صف، فاز فعلی راه‌اندازی/runtime وقتی معلوم باشد، بازه‌های فاز اخیر، و برچسب‌های محدود کارهای فعال/در صف هستند. نمونه‌های بیکار در سطح info در telemetry باقی می‌مانند. نمونه‌های زنده‌بودن فقط وقتی به هشدارهای Gateway تبدیل می‌شوند که کاری در انتظار یا در صف باشد، یا وقتی کار فعال با تأخیر پایدار حلقه رویداد هم‌پوشانی داشته باشد. جهش‌های گذرای حداکثر تأخیر هنگام کار پس‌زمینه‌ای که در غیر این صورت سالم است، در لاگ‌های debug باقی می‌مانند. آن‌ها به‌تنهایی Gateway را راه‌اندازی مجدد نمی‌کنند.

فازهای راه‌اندازی همچنین رویدادهای diagnostic.phase.completed را با زمان دیواری و زمان‌بندی CPU منتشر می‌کنند. تشخیص‌های embedded-run متوقف‌شده زمانی terminalProgressStale=true را علامت می‌زنند که آخرین پیشرفت bridge حالت terminal داشته باشد، مانند یک مورد پاسخ خام یا رویداد تکمیل پاسخ، اما Gateway همچنان embedded run را فعال در نظر بگیرد.

ضبط‌کننده زنده را بررسی کنید:

openclaw gateway stabilityopenclaw gateway stability --type payload.largeopenclaw gateway stability --json

جدیدترین بسته پایداری ذخیره‌شده را پس از خروج مرگبار، timeout خاموش‌شدن، یا شکست راه‌اندازی مجدد بررسی کنید:

openclaw gateway stability --bundle latest

از جدیدترین بسته ذخیره‌شده یک فایل zip تشخیصی بسازید:

openclaw gateway stability --bundle latest --export

بسته‌های ذخیره‌شده وقتی رویدادها وجود داشته باشند زیر ~/.openclaw/logs/stability/ قرار می‌گیرند.

گزینه‌های مفید

openclaw gateway diagnostics export \  --output openclaw-diagnostics.zip \  --log-lines 5000 \  --log-bytes 1000000

• --output <path>: در یک مسیر zip مشخص بنویس.
• --log-lines <count>: حداکثر خط‌های لاگ پاک‌سازی‌شده برای گنجاندن.
• --log-bytes <bytes>: حداکثر بایت‌های لاگ برای بررسی.
• --url <url>: نشانی WebSocket مربوط به Gateway برای عکس‌های فوری وضعیت و سلامت.
• --token <token>: توکن Gateway برای عکس‌های فوری وضعیت و سلامت.
• --password <password>: گذرواژه Gateway برای عکس‌های فوری وضعیت و سلامت.
• --timeout <ms>: timeout عکس فوری وضعیت و سلامت.
• --no-stability-bundle: از جست‌وجوی بسته پایداری ذخیره‌شده صرف‌نظر کن.
• --json: فراداده خروجی خوانا برای ماشین را چاپ کن.

غیرفعال‌کردن تشخیص‌ها

تشخیص‌ها به‌صورت پیش‌فرض فعال هستند. برای غیرفعال‌کردن ضبط‌کننده پایداری و جمع‌آوری رویداد تشخیصی:

{  diagnostics: {    enabled: false,  },}

غیرفعال‌کردن تشخیص‌ها جزئیات گزارش خطا را کاهش می‌دهد. این کار روی لاگ‌گیری عادی Gateway اثری ندارد.

عکس‌های فوری فشار بحرانی حافظه به‌صورت پیش‌فرض خاموش هستند. برای نگه‌داشتن رویدادهای تشخیصی و همچنین ثبت عکس فوری پایداری پیش از OOM:

{  diagnostics: {    memoryPressureSnapshot: true,  },}

این گزینه را فقط روی میزبان‌هایی استفاده کنید که می‌توانند اسکن اضافی فایل‌سیستم و نوشتن عکس فوری هنگام فشار بحرانی حافظه را تحمل کنند. رویدادهای عادی فشار حافظه همچنان وقتی عکس فوری خاموش است، واقعیت‌های RSS، heap، آستانه، و رشد را ثبت می‌کنند.

مرتبط

• بررسی‌های سلامت
• CLI مربوط به Gateway
• پروتکل Gateway
• لاگ‌گیری
• خروجی OpenTelemetry — جریان جداگانه برای پخش تشخیص‌ها به یک گردآورنده