ثبت گزارش‌ها

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

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

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

محل گزارش‌ها

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

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

نمایه‌های نام‌گذاری‌شده از نام فایلی شامل نمایه در همان پوشه استفاده می‌کنند:

/tmp/openclaw/openclaw-<profile>-YYYY-MM-DD.log

بخش نمایه در نام فایل با حروف کوچک نوشته می‌شود و فقط به حروف، اعداد و خط تیره محدود است. نام‌های سادهٔ دارای حروف کوچک خوانا باقی می‌مانند؛ بنابراین، شکل کوتاه --dev در openclaw-dev-YYYY-MM-DD.log می‌نویسد. حروف بزرگ و کوچک، زیرخط‌ها و خط تیره‌های واقعی از یک نویسهٔ گریز برگشت‌پذیر برای خط تیره استفاده می‌کنند تا نام‌های متمایز نمایه هرگز فایل گزارش مشترکی نداشته باشند. مقادیر بیش‌ازحد بزرگی که مستقیماً از طریق محیط تنظیم می‌شوند، از پسوند هش با طول محدود استفاده می‌کنند تا در محدودیت طول نام فایل سیستم‌فایل باقی بمانند. تنظیم صریح logging.file این پیش‌فرض‌ها را بازنویسی می‌کند.

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

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

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

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

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

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

فایل گزارش Gateway را از طریق RPC دنبال کنید:

openclaw logs --followopenclaw --dev logs --followopenclaw --profile work logs --follow

انتخاب‌گر نمایه در ریشه، همان فایل مختص نمایه را که Gateway استفاده می‌کند پیدا می‌کند؛ از جمله خواندن جایگزین CLI وقتی RPC محلی دردسترس نیست.

گزینه‌ها:

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

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

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

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

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

اگر Gateway ضمنی روی حلقهٔ بازگشتی محلی درخواست جفت‌سازی کند، هنگام اتصال بسته شود، یا پیش از پاسخ‌دادن 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> (پیش‌فرض 200) و --json نیز دردسترس‌اند.

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

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

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

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

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

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

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

خروجی کنسول

گزارش‌های کنسول از 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": "/path/to/openclaw.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) می‌نویسد تا پردازشگرهای خارجی گزارش بتوانند خط را با بازه‌های OTEL و انتشار traceparent ارائه‌دهنده هم‌بسته کنند.

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

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

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

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

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

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

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

logging.consoleStyle:

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

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

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

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

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

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

OpenClaw همچنین محتوای مرز ایمنی را که به کلاینت‌های رابط کاربری، بسته‌های پشتیبانی، ناظران تشخیصی، اعلان‌های تأیید یا ابزارهای عامل نشان داده می‌شود می‌پوشاند. الگوهای سفارشی 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.*