---
read_when:
    - تغییر خروجی یا قالب‌های ثبت گزارش
    - اشکال‌زدایی خروجی CLI یا Gateway
summary: سطوح ثبت گزارش، گزارش‌های فایلی، سبک‌های گزارش WS، و قالب‌بندی کنسول
title: لاگ‌گیری Gateway
x-i18n:
    generated_at: "2026-05-06T11:58:48Z"
    model: gpt-5.5
    provider: openai
    source_hash: 16bce5763754d13f855a46777b4c3cc7a7c966e35e0cd08a15f359fd22623bcb
    source_path: gateway/logging.md
    workflow: 16
---

# لاگ‌گیری

برای نمای کلی کاربرمحور (CLI + رابط کاربری کنترل + پیکربندی)، به [/logging](/fa/logging) مراجعه کنید.

OpenClaw دو «سطح» لاگ دارد:

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

هنگام راه‌اندازی، Gateway مدل پیش‌فرض عاملِ حل‌شده را همراه با پیش‌فرض‌های
حالتی که بر نشست‌های جدید اثر می‌گذارند لاگ می‌کند، برای مثال:

```text
agent model: openai-codex/gpt-5.5 (thinking=medium, fast=on)
```

`thinking` از عامل پیش‌فرض، پارامترهای مدل، یا پیش‌فرض سراسری عامل می‌آید؛
وقتی تنظیم نشده باشد، خلاصه راه‌اندازی `medium` را نشان می‌دهد. `fast` از
عامل پیش‌فرض یا پارامترهای `fastMode` مدل می‌آید.

## لاگر مبتنی بر فایل

- فایل لاگ چرخشی پیش‌فرض زیر `/tmp/openclaw/` است (یک فایل برای هر روز): `openclaw-YYYY-MM-DD.log`
  - تاریخ از منطقه زمانی محلی میزبان Gateway استفاده می‌کند.
- فایل‌های لاگ فعال در `logging.maxFileBytes` می‌چرخند (پیش‌فرض: 100 MB)، تا
  پنج آرشیو شماره‌دار را نگه می‌دارند و نوشتن در یک فایل فعال تازه را ادامه می‌دهند.
- مسیر و سطح فایل لاگ را می‌توان از طریق `~/.openclaw/openclaw.json` پیکربندی کرد:
  - `logging.file`
  - `logging.level`

فرمت فایل، یک شیء JSON در هر خط است.

مسیرهای کد گفت‌وگو، صدای بلادرنگ، و اتاق مدیریت‌شده از لاگر فایل مشترک برای
رکوردهای چرخه‌عمر محدود استفاده می‌کنند. این رکوردها برای اشکال‌زدایی عملیاتی
و صدور لاگ OTLP در نظر گرفته شده‌اند؛ متن رونوشت، بارهای صوتی، شناسه‌های نوبت،
شناسه‌های تماس، و شناسه‌های آیتم ارائه‌دهنده در رکورد لاگ کپی نمی‌شوند.

زبانه لاگ‌های رابط کاربری کنترل، این فایل را از طریق Gateway دنبال می‌کند (`logs.tail`).
CLI نیز می‌تواند همین کار را انجام دهد:

```bash
openclaw logs --follow
```

**جزئیات بیشتر در برابر سطوح لاگ**

- **لاگ‌های فایل** منحصراً توسط `logging.level` کنترل می‌شوند.
- `--verbose` فقط بر **میزان جزئیات کنسول** (و سبک لاگ WS) اثر می‌گذارد؛ سطح لاگ فایل را
  بالا نمی‌برد.
- برای ثبت جزئیاتی که فقط در حالت verbose هستند در لاگ‌های فایل، `logging.level` را روی `debug` یا
  `trace` تنظیم کنید.
- لاگ‌گیری trace همچنین خلاصه‌های زمان‌بندی تشخیصی برای مسیرهای داغ منتخب را شامل می‌شود،
  مانند آماده‌سازی کارخانه ابزار Plugin. ببینید
  [/tools/plugin#slow-plugin-tool-setup](/fa/tools/plugin#slow-plugin-tool-setup).

## ثبت کنسول

CLI موارد `console.log/info/warn/error/debug/trace` را ثبت می‌کند و آن‌ها را در لاگ‌های فایل می‌نویسد،
در حالی که همچنان در stdout/stderr چاپ می‌کند.

می‌توانید میزان جزئیات کنسول را مستقل از طریق موارد زیر تنظیم کنید:

- `logging.consoleLevel` (پیش‌فرض `info`)
- `logging.consoleStyle` (`pretty` | `compact` | `json`)

## پوشاندن

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

- `logging.redactSensitive`: `off` | `tools` (پیش‌فرض: `tools`)
- `logging.redactPatterns`: آرایه‌ای از رشته‌های regex (پیش‌فرض‌ها را بازنویسی می‌کند)
  - از رشته‌های regex خام (خودکار `gi`) استفاده کنید، یا اگر به پرچم‌های سفارشی نیاز دارید از `/pattern/flags`.
  - تطابق‌ها با نگه داشتن 6 نویسه اول + 4 نویسه آخر پوشانده می‌شوند (طول >= 18)، در غیر این صورت `***`.
  - پیش‌فرض‌ها انتساب‌های کلید رایج، پرچم‌های CLI، فیلدهای JSON، سربرگ‌های bearer، بلوک‌های PEM، پیشوندهای توکن محبوب، و نام‌های فیلد اعتبار پرداخت مانند شماره کارت، CVC/CVV، توکن پرداخت مشترک، و اعتبار پرداخت را پوشش می‌دهند.

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

## لاگ‌های WebSocket در Gateway

Gateway لاگ‌های پروتکل WebSocket را در دو حالت چاپ می‌کند:

- **حالت عادی (بدون `--verbose`)**: فقط نتایج RPC «جالب» چاپ می‌شوند:
  - خطاها (`ok=false`)
  - فراخوانی‌های کند (آستانه پیش‌فرض: `>= 50ms`)
  - خطاهای parse
- **حالت verbose (`--verbose`)**: همه ترافیک درخواست/پاسخ WS را چاپ می‌کند.

### سبک لاگ WS

`openclaw gateway` از یک تغییر سبک برای هر Gateway پشتیبانی می‌کند:

- `--ws-log auto` (پیش‌فرض): حالت عادی بهینه‌سازی‌شده است؛ حالت verbose از خروجی compact استفاده می‌کند
- `--ws-log compact`: خروجی compact (درخواست/پاسخ جفت‌شده) هنگام verbose
- `--ws-log full`: خروجی کامل برای هر فریم هنگام verbose
- `--compact`: نام مستعار برای `--ws-log compact`

مثال‌ها:

```bash
# optimized (only errors/slow)
openclaw gateway

# show all WS traffic (paired)
openclaw gateway --verbose --ws-log compact

# show all WS traffic (full meta)
openclaw gateway --verbose --ws-log full
```

## قالب‌بندی کنسول (لاگ‌گیری زیرسامانه)

قالب‌ساز کنسول **TTY-aware** است و خط‌های سازگارِ پیشونددار چاپ می‌کند.
لاگرهای زیرسامانه خروجی را گروه‌بندی‌شده و قابل مرور نگه می‌دارند.

رفتار:

- **پیشوندهای زیرسامانه** روی هر خط (مثلاً `[gateway]`، `[canvas]`، `[tailscale]`)
- **رنگ‌های زیرسامانه** (پایدار برای هر زیرسامانه) به‌علاوه رنگ‌بندی سطح
- **رنگ وقتی خروجی TTY است یا محیط شبیه یک ترمینال غنی به نظر می‌رسد** (`TERM`/`COLORTERM`/`TERM_PROGRAM`)، با رعایت `NO_COLOR`
- **پیشوندهای کوتاه‌شده زیرسامانه**: `gateway/` + `channels/` ابتدایی را حذف می‌کند، 2 بخش آخر را نگه می‌دارد (مثلاً `whatsapp/outbound`)
- **زیرلاگرها بر اساس زیرسامانه** (پیشوند خودکار + فیلد ساختاریافته `{ subsystem }`)
- **`logRaw()`** برای خروجی QR/UX (بدون پیشوند، بدون قالب‌بندی)
- **سبک‌های کنسول** (مثلاً `pretty | compact | json`)
- **سطح لاگ کنسول** جدا از سطح لاگ فایل (وقتی `logging.level` روی `debug`/`trace` تنظیم شده باشد، فایل جزئیات کامل را نگه می‌دارد)
- **بدنه پیام‌های WhatsApp** در سطح `debug` لاگ می‌شوند (برای دیدن آن‌ها از `--verbose` استفاده کنید)

این کار لاگ‌های فایل موجود را پایدار نگه می‌دارد و در عین حال خروجی تعاملی را قابل مرور می‌کند.

## مرتبط

- [لاگ‌گیری](/fa/logging)
- [صدور OpenTelemetry](/fa/gateway/opentelemetry)
- [صدور تشخیص‌ها](/fa/gateway/diagnostics)