ثبت گزارش

OpenClaw دو سطح اصلی برای گزارش‌ها دارد:

• گزارش‌های فایل (خطوط JSON) که توسط Gateway نوشته می‌شوند.
• خروجی کنسول که در ترمینال‌ها و رابط Debug Gateway نمایش داده می‌شود.

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

محل قرارگیری گزارش‌ها

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

/tmp/openclaw/openclaw-YYYY-MM-DD.log

تاریخ از منطقه زمانی محلی میزبان Gateway استفاده می‌کند.

هر فایل وقتی به logging.maxFileBytes برسد می‌چرخد (پیش‌فرض: 100 MB). OpenClaw تا پنج آرشیو شماره‌گذاری‌شده را کنار فایل فعال نگه می‌دارد، مانند openclaw-YYYY-MM-DD.1.log، و به‌جای سرکوب عیب‌یابی‌ها، نوشتن را در یک گزارش فعال تازه ادامه می‌دهد.

می‌توانید این را در ~/.openclaw/openclaw.json بازنویسی کنید:

{  "logging": {    "file": "/path/to/openclaw.log"  }}

روش خواندن گزارش‌ها

CLI: دنبال‌کردن زنده (توصیه‌شده)

از CLI برای دنبال‌کردن فایل گزارش Gateway از طریق RPC استفاده کنید:

openclaw logs --follow

گزینه‌های فعلی مفید:

• --local-time: نمایش مُهرهای زمانی در منطقه زمانی محلی شما
• --url <url> / --token <token> / --timeout <ms>: پرچم‌های استاندارد RPC Gateway
• --expect-final: پرچم انتظار برای پاسخ نهایی RPC پشتیبانی‌شده با عامل (اینجا از طریق لایه مشترک کلاینت پذیرفته می‌شود)

حالت‌های خروجی:

• نشست‌های TTY: خطوط گزارش ساخت‌یافته، رنگی و خوانا.
• نشست‌های غیر TTY: متن ساده.
• --json: JSON خط‌به‌خط (یک رویداد گزارش در هر خط).
• --plain: اجبار به متن ساده در نشست‌های TTY.
• --no-color: غیرفعال‌کردن رنگ‌های ANSI.

وقتی یک --url صریح می‌دهید، CLI پیکربندی یا اعتبارنامه‌های محیط را خودکار اعمال نمی‌کند؛ اگر Gateway هدف نیاز به احراز هویت دارد، خودتان --token را اضافه کنید.

در حالت JSON، CLI اشیای دارای برچسب type منتشر می‌کند:

• meta: فراداده جریان (فایل، مکان‌نما، اندازه)
• log: ورودی گزارش تجزیه‌شده
• notice: راهنمایی‌های کوتاه‌سازی / چرخش
• raw: خط گزارش تجزیه‌نشده

اگر Gateway ضمنی local loopback درخواست جفت‌سازی کند، هنگام اتصال بسته شود، یا پیش از پاسخ‌دادن logs.tail مهلتش تمام شود، openclaw logs به‌طور خودکار به گزارش فایل Gateway پیکربندی‌شده برمی‌گردد. هدف‌های صریح --url از این fallback استفاده نمی‌کنند. openclaw logs --follow سخت‌گیرتر است: در Linux وقتی در دسترس باشد از ژورنال فعال user-systemd Gateway بر اساس PID استفاده می‌کند، و در غیر این صورت به‌جای دنبال‌کردن یک فایل کناری احتمالا کهنه، تلاش دوباره برای Gateway زنده را ادامه می‌دهد.

اگر Gateway در دسترس نباشد، CLI یک راهنمای کوتاه برای اجرای دستور زیر چاپ می‌کند:

openclaw doctor

Control UI (وب)

زبانه گزارش‌ها در Control UI همان فایل را با استفاده از logs.tail دنبال می‌کند. برای روش بازکردن آن، Control UI را ببینید.

گزارش‌های فقط کانال

برای فیلترکردن فعالیت کانال (WhatsApp/Telegram/و غیره)، استفاده کنید:

openclaw channels logs --channel whatsapp

قالب‌های گزارش

گزارش‌های فایل (JSONL)

هر خط در فایل گزارش یک شیء JSON است. CLI و Control UI این ورودی‌ها را تجزیه می‌کنند تا خروجی ساخت‌یافته نمایش دهند (زمان، سطح، زیرسیستم، پیام).

رکوردهای JSONL گزارش فایل همچنین، در صورت در دسترس بودن، فیلدهای سطح بالای قابل فیلتر توسط ماشین را شامل می‌شوند:

• hostname: نام میزبان Gateway.
• message: متن پیام گزارش تخت‌شده برای جستجوی تمام‌متن.
• agent_id: شناسه عامل فعال وقتی فراخوانی گزارش زمینه عامل را حمل می‌کند.
• session_id: شناسه/کلید نشست فعال وقتی فراخوانی گزارش زمینه نشست را حمل می‌کند.
• channel: کانال فعال وقتی فراخوانی گزارش زمینه کانال را حمل می‌کند.

OpenClaw آرگومان‌های گزارش ساخت‌یافته اصلی را کنار این فیلدها حفظ می‌کند تا تجزیه‌گرهای موجود که کلیدهای شماره‌گذاری‌شده آرگومان tslog را می‌خوانند همچنان کار کنند.

فعالیت گفت‌وگو، صدای بلادرنگ، و اتاق‌های مدیریت‌شده رکوردهای گزارش چرخه‌عمر محدود را از طریق همین خط لوله گزارش فایل منتشر می‌کند. این رکوردها، در صورت در دسترس بودن، نوع رویداد، حالت، انتقال، ارائه‌دهنده، و اندازه‌گیری‌های اندازه/زمان‌بندی را شامل می‌شوند، اما متن transcript، payloadهای صوتی، شناسه‌های نوبت، شناسه‌های تماس، و شناسه‌های آیتم ارائه‌دهنده را حذف می‌کنند.

خروجی کنسول

گزارش‌های کنسول TTY-aware هستند و برای خوانایی قالب‌بندی می‌شوند:

• پیشوندهای زیرسیستم (مثلا gateway/channels/whatsapp)
• رنگ‌بندی سطح (info/warn/error)
• حالت فشرده یا JSON اختیاری

قالب‌بندی کنسول با logging.consoleStyle کنترل می‌شود.

گزارش‌های WebSocket Gateway

openclaw gateway همچنین برای ترافیک RPC گزارش‌گیری پروتکل WebSocket دارد:

• حالت عادی: فقط نتایج جالب (خطاها، خطاهای تجزیه، فراخوانی‌های کند)
• --verbose: همه ترافیک درخواست/پاسخ
• --ws-log auto|compact|full: انتخاب سبک نمایش verbose
• --compact: نام مستعار برای --ws-log compact

نمونه‌ها:

openclaw gatewayopenclaw gateway --verbose --ws-log compactopenclaw gateway --verbose --ws-log full

پیکربندی گزارش‌گیری

همه پیکربندی گزارش‌گیری زیر logging در ~/.openclaw/openclaw.json قرار دارد.

{  "logging": {    "level": "info",    "file": "/tmp/openclaw/openclaw-YYYY-MM-DD.log",    "consoleLevel": "info",    "consoleStyle": "pretty",    "redactSensitive": "tools",    "redactPatterns": ["sk-.*"]  }}

سطح‌های گزارش

• logging.level: سطح گزارش‌های فایل (JSONL).
• logging.consoleLevel: سطح پرحرفی کنسول.

می‌توانید هر دو را از طریق متغیر محیطی OPENCLAW_LOG_LEVEL بازنویسی کنید (مثلا OPENCLAW_LOG_LEVEL=debug). متغیر محیطی نسبت به فایل پیکربندی اولویت دارد، بنابراین می‌توانید بدون ویرایش openclaw.json پرحرفی را برای یک اجرا افزایش دهید. همچنین می‌توانید گزینه سراسری CLI یعنی --log-level <level> را بدهید (برای مثال، openclaw --log-level debug gateway run) که متغیر محیطی را برای همان دستور بازنویسی می‌کند.

--verbose فقط روی خروجی کنسول و پرحرفی گزارش WS اثر می‌گذارد؛ سطح گزارش‌های فایل را تغییر نمی‌دهد.

عیب‌یابی هدفمند انتقال مدل

هنگام اشکال‌زدایی فراخوانی‌های ارائه‌دهنده، به‌جای افزایش همه گزارش‌ها به debug، از پرچم‌های محیطی هدفمند استفاده کنید:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

پرچم‌های موجود:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: شروع درخواست، پاسخ fetch، سرآیندهای SDK، نخستین رویداد streaming، تکمیل stream، و خطاهای انتقال را در سطح info منتشر می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: یک خلاصه محدود از payload درخواست را در گزارش‌های درخواست مدل اضافه می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: همه نام‌های ابزار رو به مدل را در خلاصه payload اضافه می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: یک snapshot محدود و ویرایش‌شده از payload JSON را اضافه می‌کند. فقط هنگام اشکال‌زدایی استفاده کنید؛ secrets ویرایش می‌شوند اما promptها و متن پیام ممکن است همچنان وجود داشته باشند.
• OPENCLAW_DEBUG_SSE=events: زمان‌بندی نخستین رویداد و تکمیل stream را منتشر می‌کند.
• OPENCLAW_DEBUG_SSE=peek: همچنین پنج payload نخست رویداد SSE ویرایش‌شده را، با سقف برای هر رویداد، منتشر می‌کند.
• OPENCLAW_DEBUG_CODE_MODE=1: عیب‌یابی‌های سطح مدل در حالت کد را منتشر می‌کند، از جمله وقتی ابزارهای بومی ارائه‌دهنده پنهان می‌شوند چون حالت کد مالک سطح ابزار است.

این پرچم‌ها از طریق گزارش‌گیری عادی OpenClaw ثبت می‌شوند، بنابراین openclaw logs --follow و زبانه گزارش‌های Control UI آن‌ها را نشان می‌دهند. بدون این پرچم‌ها، همین عیب‌یابی‌ها در سطح debug همچنان در دسترس می‌مانند.

فراداده شروع و پاسخ [model-fetch] (ارائه‌دهنده، API، مدل، وضعیت، تأخیر، و فیلدهای درخواست مانند روش، URL، مهلت، proxy، و policy) همیشه در سطح info منتشر می‌شود، مستقل از OPENCLAW_DEBUG_MODEL_TRANSPORT، بنابراین بهداشت پایه انتقال مدل بدون پرچم‌های debug قابل مشاهده است.

همبستگی trace

گزارش‌های فایل JSONL هستند. وقتی یک فراخوانی گزارش زمینه معتبر trace عیب‌یابی را حمل می‌کند، OpenClaw فیلدهای trace را به‌عنوان کلیدهای JSON سطح بالا (traceId, spanId, parentSpanId, traceFlags) می‌نویسد تا پردازشگرهای گزارش خارجی بتوانند خط را با spanهای OTEL و انتشار traceparent ارائه‌دهنده همبسته کنند.

درخواست‌های HTTP Gateway و frameهای WebSocket Gateway یک محدوده trace درخواست داخلی ایجاد می‌کنند. گزارش‌ها و رویدادهای عیب‌یابی منتشرشده داخل آن محدوده async، وقتی زمینه trace صریحی نمی‌دهند، trace درخواست را به ارث می‌برند. traceهای اجرای عامل و فراخوانی مدل فرزند trace درخواست فعال می‌شوند، بنابراین گزارش‌های محلی، snapshotهای عیب‌یابی، spanهای OTEL، و سرآیندهای معتبر traceparent ارائه‌دهنده می‌توانند بدون ثبت محتوای خام درخواست یا مدل، با traceId به هم متصل شوند.

رکوردهای گزارش چرخه‌عمر گفت‌وگو نیز وقتی export گزارش OpenTelemetry فعال باشد، با همان ویژگی‌های محدود گزارش‌های فایل، به export گزارش diagnostics-otel می‌روند. برای انتخاب OTLP، stdout JSONL، یا هر دو مقصد، diagnostics.otel.logsExporter را پیکربندی کنید.

اندازه و زمان‌بندی فراخوانی مدل

عیب‌یابی‌های فراخوانی مدل اندازه‌گیری‌های محدود درخواست/پاسخ را بدون ثبت محتوای خام prompt یا پاسخ ضبط می‌کنند:

• requestPayloadBytes: اندازه بایتی UTF-8 payload نهایی درخواست مدل
• responseStreamBytes: اندازه بایتی UTF-8 payloadهای chunk پاسخ مدلِ stream‌شده. رویدادهای پرتکرار متن، thinking، و delta فراخوانی ابزار فقط بایت‌های افزایشی delta را به‌جای snapshotهای کامل partial حساب می‌کنند.
• timeToFirstByteMs: زمان سپری‌شده پیش از نخستین رویداد پاسخ stream‌شده
• durationMs: مدت کل فراخوانی مدل

وقتی export عیب‌یابی فعال باشد، این فیلدها برای snapshotهای عیب‌یابی، hookهای Plugin فراخوانی مدل، و spanها/metricهای فراخوانی مدل OTEL در دسترس هستند.

سبک‌های کنسول

logging.consoleStyle:

• pretty: خوانا برای انسان، رنگی، با مُهرهای زمانی.
• compact: خروجی فشرده‌تر (بهترین گزینه برای نشست‌های طولانی).
• json: JSON در هر خط (برای پردازشگرهای گزارش).

ویرایش محرمانه‌سازی

OpenClaw می‌تواند پیش از آنکه tokenهای حساس به خروجی کنسول، گزارش‌های فایل، رکوردهای گزارش OTLP، متن transcript نشست پایدارشده، یا payloadهای رویداد ابزار Control UI برسند، آن‌ها را ویرایش کند (آرگومان‌های شروع ابزار، payloadهای نتیجه جزئی/نهایی، خروجی exec مشتق‌شده، و خلاصه‌های patch):

• logging.redactSensitive: off | tools (پیش‌فرض: tools)
• logging.redactPatterns: فهرست رشته‌های regex برای بازنویسی مجموعه پیش‌فرض. الگوهای سفارشی روی پیش‌فرض‌های داخلی برای payloadهای ابزار Control UI اعمال می‌شوند، بنابراین افزودن یک الگو هرگز ویرایش مقادیری را که پیش‌فرض‌ها از قبل می‌گیرند ضعیف نمی‌کند.

گزارش‌های فایل و transcriptهای نشست JSONL می‌مانند، اما مقادیر secret مطابق پیش از نوشتن خط یا پیام روی دیسک mask می‌شوند. ویرایش به‌صورت best-effort است: روی محتوای پیام دارای متن و رشته‌های گزارش اعمال می‌شود، نه هر شناسه یا فیلد payload دودویی.

پیش‌فرض‌های داخلی credentialهای رایج API و نام فیلدهای credential پرداخت را پوشش می‌دهند، مانند شماره کارت، CVC/CVV، token پرداخت مشترک، و credential پرداخت وقتی به‌عنوان فیلدهای JSON، پارامترهای URL، پرچم‌های CLI، یا assignment ظاهر شوند.

logging.redactSensitive: "off" فقط این policy عمومی گزارش/transcript را غیرفعال می‌کند. OpenClaw همچنان payloadهای مرز ایمنی را که می‌توانند به کلاینت‌های UI، بسته‌های پشتیبانی، ناظران عیب‌یابی، promptهای تأیید، یا ابزارهای عامل نشان داده شوند ویرایش می‌کند. نمونه‌ها شامل رویدادهای فراخوانی ابزار Control UI، خروجی sessions_history، exportهای پشتیبانی عیب‌یابی، مشاهدات خطای ارائه‌دهنده، نمایش دستور تأیید exec، و گزارش‌های پروتکل WebSocket Gateway هستند. logging.redactPatterns سفارشی همچنان می‌تواند الگوهای ویژه پروژه را روی این سطوح اضافه کند.

عیب‌یابی‌ها و OpenTelemetry

عیب‌یابی‌ها رویدادهای ساخت‌یافته و قابل خواندن توسط ماشین برای اجرای مدل و دورسنجی جریان پیام هستند (webhookها، صف‌گذاری، وضعیت نشست). آن‌ها جایگزین گزارش‌ها نمی‌شوند — بلکه metricها، traceها، و exporterها را تغذیه می‌کنند. رویدادها درون فرایند منتشر می‌شوند، چه آن‌ها را export کنید چه نکنید.

دو سطح مجاور:

• export OpenTelemetry — ارسال metricها، traceها، و گزارش‌ها از طریق OTLP/HTTP به هر collector یا backend سازگار با OpenTelemetry (Grafana، Datadog، Honeycomb، New Relic، Tempo، و غیره). پیکربندی کامل، کاتالوگ سیگنال، نام‌های metric/span، متغیرهای محیطی، و مدل حریم خصوصی در صفحه‌ای اختصاصی قرار دارد: export OpenTelemetry.
• پرچم‌های عیب‌یابی — پرچم‌های هدفمند گزارش debug که گزارش‌های اضافی را بدون افزایش logging.level به logging.file هدایت می‌کنند. پرچم‌ها به بزرگی و کوچکی حروف حساس نیستند و wildcardها (telegram.*, *) را پشتیبانی می‌کنند. زیر diagnostics.flags یا از طریق بازنویسی محیطی OPENCLAW_DIAGNOSTICS=... پیکربندی کنید. راهنمای کامل: پرچم‌های عیب‌یابی.

برای فعال‌کردن رویدادهای عیب‌یابی برای Pluginها یا مقصدهای سفارشی بدون export OTLP:

{  diagnostics: { enabled: true },}

برای برون‌بری OTLP به یک گردآورنده، برون‌بری OpenTelemetry را ببینید.

نکته‌های عیب‌یابی

• Gateway در دسترس نیست؟ ابتدا openclaw doctor را اجرا کنید.
• گزارش‌ها خالی هستند؟ بررسی کنید که Gateway در حال اجراست و در مسیر فایل در logging.file می‌نویسد.
• به جزئیات بیشتری نیاز دارید؟ logging.level را روی debug یا trace تنظیم کنید و دوباره تلاش کنید.

مرتبط

• برون‌بری OpenTelemetry — برون‌بری OTLP/HTTP، کاتالوگ metric/span، مدل حریم خصوصی
• پرچم‌های تشخیص — پرچم‌های هدفمند گزارش اشکال‌زدایی
• جزئیات داخلی ثبت گزارش Gateway — سبک‌های گزارش WS، پیشوندهای زیرسامانه، و ضبط کنسول
• مرجع پیکربندی — مرجع کامل فیلدهای diagnostics.*