docs/docs/fa/logging.md

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

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

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

زبانه Logs در Control UI لاگ فایلی 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>: پرچم‌های استاندارد Gateway RPC
• --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

Control UI (وب)

زبانه Logs در Control UI همان فایل را با استفاده از logs.tail دنبال می‌کند. برای نحوه بازکردن آن، /web/control-ui را ببینید.

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

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

openclaw channels logs --channel whatsapp

قالب‌های لاگ

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

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

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

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

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

خروجی کنسول

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

• پیشوندهای زیرسامانه (مثلاً 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 یک دامنه ردگیری داخلی درخواست ایجاد می‌کنند. لاگ‌ها و رویدادهای عیب‌یابی منتشرشده داخل آن دامنه ناهمگام، وقتی زمینه ردگیری صریحی پاس ندهند، ردگیری درخواست را به ارث می‌برند. ردگیری‌های اجرای عامل و فراخوانی مدل فرزندهای ردگیری درخواست فعال می‌شوند، بنابراین لاگ‌های محلی، نماهای فوری عیب‌یابی، spanهای OTEL و سرآیندهای مورد اعتماد traceparent ارائه‌دهنده می‌توانند بدون لاگ‌کردن محتوای خام درخواست یا مدل، با traceId به هم وصل شوند.

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

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

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

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

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

logging.consoleStyle:

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

ویرایش محرمانه

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

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

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

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

عیب‌یابی و OpenTelemetry

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

دو سطح مجاور:

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

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

{
  diagnostics: { enabled: true },
}

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

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

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

مرتبط

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