لاگ‌گیری

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

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

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

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

openclaw doctor

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

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

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

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

openclaw channels logs --channel whatsapp

قالب‌های لاگ

لاگ‌های فایل (JSONL)

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

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

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

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

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

خروجی کنسول

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

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

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

لاگ‌های WebSocket Gateway

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

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

سطح‌های لاگ

• 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 اثر می‌گذارد؛ سطح لاگ فایل را تغییر نمی‌دهد.

تشخیص‌های هدفمند انتقال مدل

هنگام اشکال‌زدایی فراخوانی‌های ارائه‌دهنده، به‌جای افزایش همه لاگ‌ها به debug، از پرچم‌های محیطی هدفمند استفاده کنید:

OPENCLAW_DEBUG_MODEL_TRANSPORT=1 openclaw gatewayOPENCLAW_DEBUG_MODEL_PAYLOAD=tools OPENCLAW_DEBUG_SSE=events openclaw gateway

پرچم‌های موجود:

• OPENCLAW_DEBUG_MODEL_TRANSPORT=1: شروع درخواست، پاسخ fetch، سرآیندهای SDK، نخستین رویداد جریان، تکمیل جریان، و خطاهای انتقال را در سطح info منتشر می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=summary: خلاصه محدود payload درخواست را در لاگ‌های درخواست مدل اضافه می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=tools: همه نام ابزارهای روبه‌روی مدل را در خلاصه payload اضافه می‌کند.
• OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted: یک snapshot از payload JSON ویرایش‌شده و محدود اضافه می‌کند. فقط هنگام اشکال‌زدایی استفاده کنید؛ secretها ویرایش می‌شوند اما promptها و متن پیام ممکن است همچنان وجود داشته باشند.
• OPENCLAW_DEBUG_SSE=events: زمان‌بندی نخستین رویداد و تکمیل جریان را منتشر می‌کند.
• OPENCLAW_DEBUG_SSE=peek: همچنین پنج payload نخستین رویداد SSE ویرایش‌شده را با محدودیت برای هر رویداد منتشر می‌کند.
• OPENCLAW_DEBUG_CODE_MODE=1: تشخیص‌های سطح مدل code-mode را منتشر می‌کند، از جمله زمانی که ابزارهای بومی ارائه‌دهنده پنهان می‌شوند چون code mode مالک سطح ابزار است.

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

همبستگی trace

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

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

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

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

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

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

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

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

logging.consoleStyle:

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

ویرایش داده‌های حساس

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

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

لاگ‌های فایل و رونوشت‌های جلسه JSONL باقی می‌مانند، اما مقدارهای secret مطابق پیش از نوشته‌شدن خط یا پیام روی دیسک masked می‌شوند. ویرایش داده‌های حساس best-effort است: روی محتوای پیام‌های متنی و رشته‌های لاگ اعمال می‌شود، نه روی هر شناسه یا فیلد payload دودویی.

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

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

تشخیص‌ها و OpenTelemetry

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

دو سطح مجاور:

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

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

{  diagnostics: { enabled: true },}

برای صدور OTLP به یک collector، صادرکردن OpenTelemetry را ببینید.

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

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

مرتبط

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