لاگ‌گیری

برای نمای کلی کاربرمحور (CLI + Control UI + پیکربندی)، /logging را ببینید.

OpenClaw دو «سطح» لاگ دارد:

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

هنگام راه‌اندازی، Gateway مدل پیش‌فرض عاملِ حل‌شده را همراه با پیش‌فرض‌های حالتی که روی نشست‌های جدید اثر می‌گذارند لاگ می‌کند، برای مثال:

agent model: openai/gpt-5.5 (thinking=medium, fast=on)

thinking از عامل پیش‌فرض، پارامترهای مدل، یا پیش‌فرض سراسری عامل می‌آید؛ وقتی تنظیم نشده باشد، خلاصه راه‌اندازی medium را نشان می‌دهد. fast از عامل پیش‌فرض یا پارامترهای fastMode مدل می‌آید.

لاگر مبتنی بر فایل

• فایل لاگ چرخشی پیش‌فرض زیر /tmp/openclaw/ قرار دارد (یک فایل در هر روز): openclaw-YYYY-MM-DD.log
  • تاریخ از منطقه زمانی محلی میزبان Gateway استفاده می‌کند.
• فایل‌های لاگ فعال در logging.maxFileBytes می‌چرخند (پیش‌فرض: 100 MB)، تا پنج آرشیو شماره‌گذاری‌شده را نگه می‌دارند و نوشتن در یک فایل فعال تازه را ادامه می‌دهند.
• مسیر و سطح فایل لاگ را می‌توان از طریق ~/.openclaw/openclaw.json پیکربندی کرد:
  • logging.file
  • logging.level

قالب فایل، یک شیء JSON در هر خط است.

مسیرهای کد گفت‌وگو، صدای بلادرنگ، و اتاق مدیریت‌شده از لاگر فایل مشترک برای رکوردهای چرخه عمر محدود استفاده می‌کنند. این رکوردها برای اشکال‌زدایی عملیاتی و صدور لاگ OTLP در نظر گرفته شده‌اند؛ متن رونوشت، payloadهای صوتی، شناسه‌های نوبت، شناسه‌های تماس، و شناسه‌های آیتم provider در رکورد لاگ کپی نمی‌شوند.

زبانه Logs در Control UI این فایل را از طریق Gateway دنبال می‌کند (logs.tail). CLI هم می‌تواند همین کار را انجام دهد:

openclaw logs --follow

پرحرفی در برابر سطوح لاگ

• لاگ‌های فایل فقط با logging.level کنترل می‌شوند.
• --verbose فقط روی پرحرفی کنسول (و سبک لاگ WS) اثر می‌گذارد؛ سطح لاگ فایل را بالا نمی‌برد.
• برای ثبت جزئیات فقط-پرحرف در لاگ‌های فایل، logging.level را روی debug یا trace تنظیم کنید.
• لاگ‌گیری Trace همچنین شامل خلاصه‌های زمان‌بندی تشخیصی برای مسیرهای داغ منتخب است، مانند آماده‌سازی کارخانه ابزار Plugin. /tools/plugin#slow-plugin-tool-setup را ببینید.

ضبط کنسول

CLI فراخوانی‌های console.log/info/warn/error/debug/trace را ضبط می‌کند و آن‌ها را در لاگ‌های فایل می‌نویسد، در حالی که همچنان در stdout/stderr چاپ می‌کند.

می‌توانید پرحرفی کنسول را به‌طور مستقل با این موارد تنظیم کنید:

• logging.consoleLevel (پیش‌فرض info)
• logging.consoleStyle (pretty | compact | json)

پوشاندن داده‌ها

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

• logging.redactSensitive: off | tools (پیش‌فرض: tools)
• logging.redactPatterns: آرایه‌ای از رشته‌های regex (پیش‌فرض‌ها را بازنویسی می‌کند)
  • از رشته‌های regex خام (خودکار gi) استفاده کنید، یا اگر به flagهای سفارشی نیاز دارید از /pattern/flags استفاده کنید.
  • تطبیق‌ها با نگه‌داشتن 6 نویسه اول + 4 نویسه آخر پنهان می‌شوند (طول >= 18)، در غیر این صورت ***.
  • پیش‌فرض‌ها انتساب‌های کلید رایج، flagهای CLI، فیلدهای JSON، headerهای bearer، بلوک‌های PEM، پیشوندهای token محبوب، و نام‌های فیلد اعتبار پرداخت مانند شماره کارت، CVC/CVV، token پرداخت مشترک، و اعتبار پرداخت را پوشش می‌دهند.

برخی مرزهای ایمنی بدون توجه به logging.redactSensitive همیشه داده‌ها را می‌پوشانند. این شامل رویدادهای فراخوانی ابزار Control UI، خروجی ابزار sessions_history، صدور پشتیبانی diagnostics، مشاهده‌های خطای provider، نمایش فرمان تأیید exec، و لاگ‌های پروتکل WebSocket در Gateway می‌شود. این سطح‌ها همچنان ممکن است از logging.redactPatterns به‌عنوان الگوهای اضافی استفاده کنند، اما redactSensitive: "off" باعث نمی‌شود secretهای خام را منتشر کنند.

لاگ‌های WebSocket در Gateway

Gateway لاگ‌های پروتکل WebSocket را در دو حالت چاپ می‌کند:

• حالت عادی (بدون --verbose): فقط نتایج RPC «جالب» چاپ می‌شوند:
  • خطاها (ok=false)
  • فراخوانی‌های کند (آستانه پیش‌فرض: >= 50ms)
  • خطاهای parse
• حالت پرحرف (--verbose): تمام ترافیک درخواست/پاسخ WS را چاپ می‌کند.

سبک لاگ WS

openclaw gateway از یک سوییچ سبک برای هر Gateway پشتیبانی می‌کند:

• --ws-log auto (پیش‌فرض): حالت عادی بهینه‌سازی شده است؛ حالت پرحرف از خروجی compact استفاده می‌کند
• --ws-log compact: خروجی compact (درخواست/پاسخ جفت‌شده) هنگام پرحرف بودن
• --ws-log full: خروجی کامل برای هر frame هنگام پرحرف بودن
• --compact: نام مستعار برای --ws-log compact

نمونه‌ها:

# optimized (only errors/slow)openclaw gateway # show all WS traffic (paired)openclaw gateway --verbose --ws-log compact # show all WS traffic (full meta)openclaw gateway --verbose --ws-log full

قالب‌بندی کنسول (لاگ‌گیری زیرسیستم)

قالب‌ساز کنسول TTY-aware است و خطوط سازگار و پیشونددار چاپ می‌کند. لاگرهای زیرسیستم خروجی را گروه‌بندی‌شده و قابل اسکن نگه می‌دارند.

رفتار:

• پیشوندهای زیرسیستم در هر خط (مثلاً [gateway]، [canvas]، [tailscale])
• رنگ‌های زیرسیستم (پایدار برای هر زیرسیستم) به‌همراه رنگ‌آمیزی سطح
• رنگ وقتی خروجی TTY است یا محیط شبیه ترمینال غنی به نظر می‌رسد (TERM/COLORTERM/TERM_PROGRAM)، با رعایت NO_COLOR
• پیشوندهای کوتاه‌شده زیرسیستم: gateway/ + channels/ ابتدایی را حذف می‌کند، 2 بخش آخر را نگه می‌دارد (مثلاً whatsapp/outbound)
• زیر-لاگرها بر اساس زیرسیستم (پیشوند خودکار + فیلد ساخت‌یافته { subsystem })
• logRaw() برای خروجی QR/UX (بدون پیشوند، بدون قالب‌بندی)
• سبک‌های کنسول (مثلاً pretty | compact | json)
• سطح لاگ کنسول جدا از سطح لاگ فایل است (وقتی logging.level روی debug/trace تنظیم شده باشد، فایل جزئیات کامل را نگه می‌دارد)
• بدنه‌های پیام WhatsApp در سطح debug لاگ می‌شوند (برای دیدن آن‌ها از --verbose استفاده کنید)

این کار لاگ‌های فایل موجود را پایدار نگه می‌دارد و در عین حال خروجی تعاملی را قابل اسکن می‌کند.

مرتبط

• لاگ‌گیری
• صدور OpenTelemetry
• صدور Diagnostics