لاگ‌گیری

OpenClaw دو سطح اصلی برای لاگ دارد:

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

زبانه لاگ‌ها در رابط کاربری کنترل، لاگ فایل 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 از این بازگشت استفاده نمی‌کنند.

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

openclaw doctor

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

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

# لاگ‌های فقط کانال

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

openclaw channels logs --channel whatsapp

# قالب‌های لاگ

# لاگ‌های فایل (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 gateway
openclaw gateway --verbose --ws-log compact
openclaw 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 اثر می‌گذارد؛ سطح‌های لاگ فایل را تغییر نمی‌دهد.

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

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

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

رکوردهای لاگ چرخه عمر Talk نیز وقتی خروجی لاگ OpenTelemetry فعال باشد، با همان ویژگی‌های محدود لاگ‌های فایل به لاگ‌های OTLP جریان می‌یابند.

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

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

• requestPayloadBytes: اندازه بایتی UTF-8 بار درخواست نهایی مدل
• responseStreamBytes: اندازه بایتی UTF-8 رویدادهای پاسخ مدلِ جریانی
• timeToFirstByteMs: زمان سپری‌شده پیش از نخستین رویداد پاسخ جریانی
• durationMs: مدت کل فراخوانی مدل

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

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

logging.consoleStyle:

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

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

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

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

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

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

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

# تشخیص‌ها و OpenTelemetry

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

دو سطح مجاور:

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

برای فعال‌کردن رویدادهای تشخیصی برای Pluginها یا خروجی‌های سفارشی بدون خروجی OTLP:

{
  diagnostics: { enabled: true },
}

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

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

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

# مرتبط

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