docs/docs/fa/logging.md

read_when	summary	title	x-i18n
به یک مرور کلی مناسب مبتدیان دربارهٔ لاگ‌گیری OpenClaw نیاز دارید می‌خواهید سطوح، قالب‌ها یا پنهان‌سازی اطلاعات حساس لاگ را پیکربندی کنید در حال عیب‌یابی هستید و باید لاگ‌ها را سریع پیدا کنید	لاگ‌های فایل، خروجی کنسول، دنبال‌کردن در CLI، و زبانهٔ لاگ‌های رابط کاربری کنترل	ثبت گزارش	generated_at model provider source_hash source_path workflow 2026-05-01T11:50:19Z gpt-5.5 openai d41ce5b1ae30fe1ca65577abe387fc266bd281686acb10098f82b8e78dfaa357 logging.md 16

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 از این fallback استفاده نمی‌کنند.

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

openclaw doctor

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

زبانهٔ گزارش‌ها در رابط کنترل همان فایل را با استفاده از logs.tail دنبال می‌کند. برای نحوهٔ بازکردن آن، /web/control-ui را ببینید.

گزارش‌های مخصوص کانال

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

openclaw channels logs --channel whatsapp

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

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

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

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

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

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

خروجی کنسول

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

• پیشوندهای زیرسامانه (مثلاً gateway/channels/whatsapp)
• رنگ‌بندی سطح‌ها (info/warn/error)
• حالت فشرده یا 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 یک دامنهٔ ردیابی داخلی درخواست ایجاد می‌کنند. گزارش‌ها و رویدادهای تشخیصی منتشرشده در همان دامنهٔ async وقتی زمینهٔ ردیابی صریحی پاس ندهند، ردیابی درخواست را به ارث می‌برند. ردیابی‌های اجرای عامل و فراخوانی مدل فرزند ردیابی درخواست فعال می‌شوند، بنابراین گزارش‌های محلی، snapshotهای تشخیصی، spanهای OTEL، و سرآیندهای مورد اعتماد traceparent ارائه‌دهنده می‌توانند بدون ثبت محتوای خام درخواست یا مدل، با traceId به هم متصل شوند.

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

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

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

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

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

logging.consoleStyle:

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

پنهان‌سازی

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

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

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

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

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

تشخیص‌ها و OpenTelemetry

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

دو سطح مجاور:

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

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

{
  diagnostics: { enabled: true },
}

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

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

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

مرتبط

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