ثبت گزارش‌ها

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

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

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

محل گزارش‌ها

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

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

تاریخ بر اساس منطقهٔ زمانی محلی میزبان Gateway است. وقتی /tmp/openclaw ناامن یا در دسترس نباشد (و همیشه در Windows)، OpenClaw به‌جای آن از یک پوشهٔ مختص کاربر با نام openclaw-<uid> در پوشهٔ موقت سیستم‌عامل استفاده می‌کند. فایل‌های گزارش تاریخ‌دار پس از ۲۴ ساعت پاک می‌شوند.

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

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

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

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

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

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

openclaw logs --follow

گزینه‌ها:

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

• نشست‌های TTY: خطوط گزارش ساختاریافته، رنگی و خوانا.
• نشست‌های غیر TTY: متن ساده.

وقتی --url را به‌صراحت وارد می‌کنید، CLI اطلاعات اعتبارسنجی پیکربندی یا محیط را به‌طور خودکار اعمال نمی‌کند؛ خودتان --token را وارد کنید، در غیر این صورت فراخوانی با خطای gateway url override requires explicit credentials شکست می‌خورد.

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

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

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

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

openclaw doctor

رابط کنترل (وب)

زبانهٔ گزارش‌ها در رابط کنترل، همان فایل را با استفاده از logs.tail به‌صورت زنده دنبال می‌کند. برای نحوهٔ بازکردن آن، رابط کنترل را ببینید.

گزارش‌های مختص کانال

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

openclaw channels logs --channel whatsapp

مقدار پیش‌فرض --channel برابر all است؛ --lines <n> (پیش‌فرض ۲۰۰) و --json نیز در دسترس هستند.

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

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

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

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

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

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

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

خروجی کنسول

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

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

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

گزارش‌های WebSocket در Gateway

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

• حالت عادی: فقط نتایج مهم (خطاها، خطاهای تجزیه، فراخوانی‌های کند)
• --verbose: تمام ترافیک درخواست/پاسخ
• --ws-log auto|compact|full: انتخاب سبک نمایش مشروح
• --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-.*"]  }}

سطوح گزارش

سطوح: silent، fatal، error، warn، info، debug، trace.

• logging.level: سطح گزارش‌های فایل (JSONL) (پیش‌فرض: info).
• 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: آغاز درخواست، پاسخ واکشی، سرآیندهای SDK، نخستین رویداد جریانی، تکمیل جریان و خطاهای انتقال را در سطح info منتشر می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: خلاصه‌ای محدودشده از بار درخواست را در گزارش‌های درخواست مدل می‌گنجاند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: نام تمام ابزارهای قابل مشاهده برای مدل را در خلاصهٔ بار می‌گنجاند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: یک تصویر لحظه‌ای JSON با اطلاعات حساس پوشانده‌شده و اندازهٔ محدود را می‌گنجاند. فقط هنگام اشکال‌زدایی استفاده کنید؛ اسرار پوشانده می‌شوند، اما ممکن است اعلان‌ها و متن پیام همچنان وجود داشته باشند.
• OPENCLAW_DEBUG_SSE=events: زمان‌بندی نخستین رویداد و تکمیل جریان را منتشر می‌کند.
• OPENCLAW_DEBUG_SSE=peek: همچنین پنج بار رویداد SSE نخست را با اطلاعات حساس پوشانده‌شده و اندازهٔ محدود برای هر رویداد منتشر می‌کند.
• OPENCLAW_DEBUG_CODE_MODE=1: داده‌های تشخیصی سطح مدل در حالت کد را منتشر می‌کند، از جمله زمانی که ابزارهای بومی ارائه‌دهنده پنهان می‌شوند، زیرا حالت کد مالک سطح ابزار است.

این پرچم‌ها از طریق گزارش‌گیری عادی OpenClaw ثبت می‌شوند؛ بنابراین openclaw logs --follow و زبانهٔ گزارش‌ها در رابط کنترل آن‌ها را نمایش می‌دهند. بدون این پرچم‌ها، همان داده‌های تشخیصی در سطح debug در دسترس می‌مانند.

فرادادهٔ آغاز و پاسخ [model-fetch] (ارائه‌دهنده، API، مدل، وضعیت، تأخیر و فیلدهای درخواست مانند روش، URL، مهلت زمانی، پروکسی و خط‌مشی) بدون توجه به OPENCLAW_DEBUG_MODEL_TRANSPORT همیشه در سطح info منتشر می‌شود؛ بنابراین اصول پایهٔ سلامت انتقال مدل بدون پرچم‌های اشکال‌زدایی قابل مشاهده است.

هم‌بستگی ردیابی

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

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

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

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

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

• requestPayloadBytes: اندازهٔ بایتی UTF-8 بار نهایی درخواست مدل
• responseStreamBytes: اندازهٔ بایتی UTF-8 بار قطعه‌های پاسخ جریانی مدل. رویدادهای پرتکرار متن، تفکر و تغییرات فراخوانی ابزار، به‌جای تصویرهای لحظه‌ای کامل partial فقط بایت‌های افزایشی delta را محاسبه می‌کنند.
• timeToFirstByteMs: زمان سپری‌شده پیش از نخستین رویداد پاسخ جریانی
• durationMs: مدت کل فراخوانی مدل

وقتی صدور داده‌های تشخیصی فعال باشد، این فیلدها برای تصاویر لحظه‌ای تشخیصی، قلاب‌های Plugin فراخوانی مدل و spanها/معیارهای OTEL فراخوانی مدل در دسترس هستند.

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

logging.consoleStyle:

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

پوشاندن اطلاعات حساس

OpenClaw می‌تواند توکن‌های حساس را پیش از رسیدن به خروجی کنسول، گزارش‌های فایل، رکوردهای گزارش OTLP، متن رونوشت نشست ذخیره‌شده یا بارهای رویداد ابزار در رابط کنترل (آرگومان‌های آغاز ابزار، بارهای نتیجهٔ جزئی/نهایی، خروجی اجرای استخراج‌شده و خلاصه‌های وصله) بپوشاند:

• logging.redactSensitive: off | tools (پیش‌فرض: tools)
• logging.redactPatterns: فهرستی از رشته‌های عبارت منظم که مجموعهٔ پیش‌فرض خروجی گزارش/رونوشت را جایگزین می‌کند. برای بارهای ابزار رابط کنترل، الگوهای سفارشی افزون بر پیش‌فرض‌های داخلی اعمال می‌شوند؛ بنابراین افزودن یک الگو هرگز پوشاندن مقادیری را که پیش‌فرض‌ها از قبل تشخیص می‌دهند، تضعیف نمی‌کند.

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

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

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

عیب‌یابی و OpenTelemetry

عیب‌یابی‌ها رویدادهایی ساخت‌یافته و ماشین‌خوان برای اجرای مدل و دورسنجی جریان پیام (Webhookها، صف‌بندی و وضعیت نشست) هستند. آن‌ها جایگزین گزارش‌ها نمی‌شوند؛ بلکه داده‌های سنجه‌ها، ردگیری‌ها و صادرکننده‌ها را تأمین می‌کنند. رویدادها به‌طور پیش‌فرض درون‌پردازشی منتشر می‌شوند (برای غیرفعال‌کردن آن‌ها، diagnostics.enabled: false را تنظیم کنید)؛ صدور آن‌ها فرایندی جداگانه است.

دو سطح مرتبط:

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

برای صدور OTLP به یک گردآورنده، به صدور OpenTelemetry مراجعه کنید.

نکات رفع اشکال

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

مطالب مرتبط

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