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

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` بازنویسی کنید:

```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** در رابط کنترل همان فایل را با استفاده از `logs.tail` دنبال می‌کند.
برای نحوه بازکردن آن، [رابط کنترل](/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 را می‌خوانند همچنان کار کنند.

فعالیت گفت‌وگو، صدای بلادرنگ، و اتاق‌های مدیریت‌شده رکوردهای لاگ چرخه‌عمر محدود را
از طریق همین خط لوله لاگ فایل منتشر می‌کند. این رکوردها نوع رویداد،
حالت، انتقال، ارائه‌دهنده، و اندازه/زمان‌بندی را در صورت دردسترس‌بودن شامل می‌شوند، اما
متن رونوشت، 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`

مثال‌ها:

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

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

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

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

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

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

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

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

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

## مرتبط

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