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

```json
{
  "logging": {
    "file": "/path/to/openclaw.log"
  }
}
```

## نحوهٔ خواندن گزارش‌ها

### CLI: دنبال‌کردن زنده (توصیه‌شده)

از CLI برای دنبال‌کردن فایل گزارش gateway از طریق RPC استفاده کنید:

```bash
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 یک راهنمای کوتاه برای اجرای دستور زیر چاپ می‌کند:

```bash
openclaw doctor
```

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

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

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

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

```bash
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`

نمونه‌ها:

```bash
openclaw gateway
openclaw gateway --verbose --ws-log compact
openclaw gateway --verbose --ws-log full
```

## پیکربندی گزارش‌گیری

همهٔ پیکربندی گزارش‌گیری زیر `logging` در `~/.openclaw/openclaw.json` قرار دارد.

```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](/fa/gateway/opentelemetry).
- **پرچم‌های تشخیصی** — پرچم‌های هدفمند گزارش اشکال‌زدایی که بدون افزایش `logging.level`، گزارش‌های اضافی را به `logging.file` هدایت می‌کنند. پرچم‌ها به بزرگی/کوچکی حروف حساس نیستند و از wildcardها (`telegram.*`، `*`) پشتیبانی می‌کنند. زیر `diagnostics.flags` یا از طریق بازنویسی محیطی `OPENCLAW_DIAGNOSTICS=...` پیکربندی کنید. راهنمای کامل: [پرچم‌های تشخیصی](/fa/diagnostics/flags).

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

```json5
{
  diagnostics: { enabled: true },
}
```

برای export به OTLP به یک گردآورنده، [export به OpenTelemetry](/fa/gateway/opentelemetry) را ببینید.

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

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

## مرتبط

- [export به OpenTelemetry](/fa/gateway/opentelemetry) — export به OTLP/HTTP، کاتالوگ metric/span، مدل حریم خصوصی
- [پرچم‌های تشخیصی](/fa/diagnostics/flags) — پرچم‌های هدفمند گزارش اشکال‌زدایی
- [جزئیات داخلی گزارش‌گیری Gateway](/fa/gateway/logging) — سبک‌های گزارش WS، پیشوندهای زیرسامانه، و capture کنسول
- [مرجع پیکربندی](/fa/gateway/configuration-reference#diagnostics) — مرجع کامل فیلدهای `diagnostics.*`
