# لاگ‌گیری

برای نمای کلی کاربرمحور (CLI + رابط کاربری کنترل + پیکربندی)، به /logging مراجعه کنید.

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

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

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

agent model: openai-codex/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 در نظر گرفته شده‌اند؛ متن رونوشت، بارهای صوتی، شناسه‌های نوبت، شناسه‌های تماس، و شناسه‌های آیتم ارائه‌دهنده در رکورد لاگ کپی نمی‌شوند.

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

openclaw logs --follow

جزئیات بیشتر در برابر سطوح لاگ

• لاگ‌های فایل منحصراً توسط logging.level کنترل می‌شوند.
• --verbose فقط بر میزان جزئیات کنسول (و سبک لاگ WS) اثر می‌گذارد؛ سطح لاگ فایل را بالا نمی‌برد.
• برای ثبت جزئیاتی که فقط در حالت verbose هستند در لاگ‌های فایل، 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 می‌تواند توکن‌های حساس را پیش از خروج خروجی لاگ یا رونوشت از فرایند بپوشاند. این خط‌مشی پوشاندن لاگ در سینک‌های کنسول، فایل لاگ، رکورد لاگ OTLP، و متن رونوشت نشست اعمال می‌شود، بنابراین مقدارهای محرمانه مطابق پیش از نوشته‌شدن خطوط JSONL یا پیام‌ها روی دیسک پوشانده می‌شوند.

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

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

# لاگ‌های WebSocket در Gateway

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

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

# سبک لاگ WS

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

• --ws-log auto (پیش‌فرض): حالت عادی بهینه‌سازی‌شده است؛ حالت verbose از خروجی compact استفاده می‌کند
• --ws-log compact: خروجی compact (درخواست/پاسخ جفت‌شده) هنگام verbose
• --ws-log full: خروجی کامل برای هر فریم هنگام verbose
• --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
• صدور تشخیص‌ها