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

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

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

# شروع سریع

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 از سازوکار بومی OpenAI Codex استفاده می‌کند، همان تأیید اجرا، بارگذاری بازخورد OpenAI را نیز برای رشته‌های اجرای Codex که OpenClaw از آن‌ها اطلاع دارد پوشش می‌دهد. این بارگذاری جدا از zip محلی Gateway است و فقط برای نشست‌های سازوکار Codex ظاهر می‌شود. پیش از تأیید، درخواست توضیح می‌دهد که تأیید عیب‌یابی، بازخورد Codex را نیز ارسال می‌کند، اما شناسه‌های نشست یا رشته Codex را فهرست نمی‌کند. پس از تأیید، پاسخ چت کانال‌ها، شناسه‌های نشست OpenClaw، شناسه‌های رشته Codex، و فرمان‌های resume محلی را برای رشته‌هایی که به سرورهای OpenAI ارسال شده‌اند فهرست می‌کند. اگر تأیید را رد یا نادیده بگیرید، OpenClaw خروجی را اجرا نمی‌کند، بازخورد Codex را نمی‌فرستد، و شناسه‌های Codex را چاپ نمی‌کند.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw 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>: URL WebSocket Gateway برای snapshotهای وضعیت و سلامت.
• --token <token>: token Gateway برای snapshotهای وضعیت و سلامت.
• --password <password>: رمز عبور Gateway برای snapshotهای وضعیت و سلامت.
• --timeout <ms>: timeout برای snapshot وضعیت و سلامت.
• --no-stability-bundle: از جست‌وجوی بسته پایداری ذخیره‌شده صرف‌نظر کنید.
• --json: فراداده خروجی قابل خواندن توسط ماشین را چاپ کنید.

# غیرفعال‌کردن عیب‌یابی

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

{
  diagnostics: {
    enabled: false,
  },
}

غیرفعال‌کردن عیب‌یابی، جزئیات گزارش باگ را کاهش می‌دهد. این کار بر لاگ‌گیری عادی Gateway اثری ندارد.

# مرتبط

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