---
read_when:
    - تغییر خروجی یا قالب‌های گزارش‌گیری
    - اشکال‌زدایی خروجی CLI یا Gateway
summary: سطوح ثبت گزارش، گزارش‌های فایل، سبک‌های گزارش WS و قالب‌بندی کنسول
title: لاگ‌گیری Gateway
x-i18n:
    generated_at: "2026-07-27T14:08:49Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: f0b11a68611032c29c31091b2411982487e7f5df3ecf4f1e3b586e7d21e543d3
    source_path: gateway/logging.md
    workflow: 16
---

# گزارش‌گیری

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

OpenClaw دو سطح گزارش دارد:

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

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

```text
مدل عامل: openai/gpt-5.6-sol (تفکر=متوسط، سریع=روشن)
```

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

## گزارش‌گیر مبتنی بر فایل

- فایل‌های گزارش چرخشی پیش‌فرض در `/tmp/openclaw/` قرار دارند (یک فایل برای هر روز) و بر اساس منطقه زمانی محلی میزبان Gateway تاریخ‌گذاری می‌شوند. پروفایل پیش‌فرض از `openclaw-YYYY-MM-DD.log` استفاده می‌کند؛ پروفایل‌های نام‌گذاری‌شده از `openclaw-<profile>-YYYY-MM-DD.log` استفاده می‌کنند (برای مثال، `openclaw-dev-YYYY-MM-DD.log`). اگر آن دایرکتوری ناامن یا غیرقابل‌نوشتن باشد (مالک نادرست، قابل‌نوشتن برای همه یا پیوند نمادین)، OpenClaw در عوض به مسیر `os.tmpdir()/openclaw-<uid>` با دامنه کاربر برمی‌گردد؛ در Windows همیشه از همان مسیر جایگزین دایرکتوری موقت سیستم‌عامل استفاده می‌کند.
- فایل‌های گزارش فعال در `logging.maxFileBytes` می‌چرخند (پیش‌فرض: 100 MB)، حداکثر پنج بایگانی شماره‌گذاری‌شده (`.1` تا `.5`) را نگه می‌دارند و نوشتن را در یک فایل فعال تازه ادامه می‌دهند.
- مسیر و سطح فایل گزارش را از طریق `~/.openclaw/openclaw.json` پیکربندی کنید: `logging.file`، `logging.level`.
- قالب فایل، یک شیء JSON در هر خط است.

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

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

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

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

- **گزارش‌های فایل** منحصراً با `logging.level` کنترل می‌شوند.
- `--verbose` فقط بر **میزان جزئیات کنسول** (و سبک گزارش WS) اثر می‌گذارد - سطح گزارش فایل را افزایش **نمی‌دهد**.
- برای ثبت جزئیاتی که فقط در حالت پرجزئیات موجودند در گزارش‌های فایل، `logging.level` را روی `debug` یا `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`؛ در TTY به‌طور پیش‌فرض `pretty` و در غیر این صورت `compact`)

## پنهان‌سازی

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

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

مرزهای ایمنی مانند رویدادهای فراخوانی ابزار در رابط کنترل، خروجی `sessions_history`، صدور داده‌های تشخیصی، خطاهای ارائه‌دهنده، نمایش تأیید اجرای دستور و گزارش‌های WebSocket مربوط به Gateway همیشه پنهان‌سازی می‌شوند. `logging.redactPatterns` الگوهای مختص استقرار را اضافه می‌کند.

## گزارش‌های WebSocket مربوط به Gateway

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

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

### سبک گزارش WS

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

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

```bash
# بهینه‌شده (فقط خطاها/موارد کند)
openclaw gateway

# نمایش تمام ترافیک WS (جفت‌شده)
openclaw gateway --verbose --ws-log compact

# نمایش تمام ترافیک WS (فراداده کامل)
openclaw gateway --verbose --ws-log full
```

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

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

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

این کار ضمن ثابت نگه‌داشتن گزارش‌های فایل، خروجی تعاملی را قابل‌مرور می‌کند.

## مرتبط

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