---
read_when:
    - تحتاج إلى نظرة عامة مبسطة للمبتدئين حول التسجيل في OpenClaw
    - تريد تهيئة مستويات السجل أو تنسيقاته أو إخفاء البيانات الحساسة
    - أنت تقوم باستكشاف الأخطاء وإصلاحها وتحتاج إلى العثور على السجلات بسرعة
summary: سجلات الملفات، ومخرجات الطرفية، وتتبع CLI، وعلامة تبويب السجلات في Control UI
title: التسجيل
x-i18n:
    generated_at: "2026-04-26T11:34:15Z"
    model: gpt-5.4
    provider: openai
    source_hash: 6fa55caa65a2a06a757e37ad64c5fd030f958cf6827596db5c183c6c6db2ed9b
    source_path: logging.md
    workflow: 15
---

يمتلك OpenClaw سطحين رئيسيين للتسجيل:

- **سجلات الملفات** (JSON lines) التي يكتبها 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`:

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

## كيفية قراءة السجلات

### CLI: تتبع مباشر (موصى به)

استخدم CLI لتتبع ملف سجل Gateway عبر RPC:

```bash
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 تلقائيًا بيانات اعتماد التهيئة أو
البيئة؛ لذا أدرج `--token` بنفسك إذا كانت Gateway الهدف
تتطلب المصادقة.

في وضع JSON، يصدر CLI كائنات موسومة بـ `type`:

- `meta`: بيانات وصفية للتدفق (الملف، والمؤشر، والحجم)
- `log`: إدخال سجل محلل
- `notice`: تلميحات الاقتطاع / التدوير
- `raw`: سطر سجل غير محلل

إذا طلبت Gateway المحلية على loopback الاقتران، يعود `openclaw logs` تلقائيًا إلى
ملف السجل المحلي المهيأ. ولا تستخدم أهداف `--url` الصريحة هذا الرجوع.

إذا تعذر الوصول إلى Gateway، يطبع CLI تلميحًا قصيرًا لتشغيل:

```bash
openclaw doctor
```

### Control UI (الويب)

تتبع علامة تبويب **Logs** في Control UI الملف نفسه باستخدام `logs.tail`.
راجع [/web/control-ui](/ar/web/control-ui) لمعرفة كيفية فتحها.

### سجلات القنوات فقط

لتصفية نشاط القنوات (WhatsApp/Telegram/إلخ)، استخدم:

```bash
openclaw channels logs --channel whatsapp
```

## تنسيقات السجل

### سجلات الملفات (JSONL)

كل سطر في ملف السجل هو كائن JSON. ويقوم CLI وControl UI بتحليل هذه
الإدخالات لعرض خرج مهيكل (الوقت، والمستوى، والنظام الفرعي، والرسالة).

### مخرجات الطرفية

سجلات الطرفية **مدركة لـ TTY** ومهيأة لتحسين القراءة:

- بادئات الأنظمة الفرعية (مثل `gateway/channels/whatsapp`)
- تلوين المستوى (info/warn/error)
- وضع compact أو JSON اختياري

يتم التحكم في تنسيق الطرفية عبر `logging.consoleStyle`.

### سجلات WebSocket الخاصة بـ Gateway

تحتوي `openclaw gateway` أيضًا على تسجيل لبروتوكول WebSocket لحركة RPC:

- الوضع العادي: النتائج المهمة فقط (الأخطاء، وأخطاء التحليل، والاستدعاءات البطيئة)
- `--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؛ ولا يغيّر
مستويات سجلات الملفات.

### أنماط الطرفية

`logging.consoleStyle`:

- `pretty`: مناسب للبشر، وملون، ويتضمن طوابع زمنية.
- `compact`: خرج أكثر إحكامًا (الأفضل للجلسات الطويلة).
- `json`: JSON في كل سطر (لمعالجات السجل).

### إخفاء البيانات الحساسة

يمكن لملخصات الأدوات إخفاء الرموز الحساسة قبل وصولها إلى الطرفية:

- `logging.redactSensitive`: ‏`off` | `tools` (الافتراضي: `tools`)
- `logging.redactPatterns`: قائمة سلاسل regex لتجاوز المجموعة الافتراضية

ينطبق إخفاء البيانات الحساسة عند واجهات التسجيل على **مخرجات الطرفية** و**تشخيصات الطرفية
الموجّهة إلى stderr** و**سجلات الملفات**. وتظل سجلات الملفات بصيغة JSONL، لكن يتم
إخفاء القيم السرية المطابقة قبل كتابة السطر إلى القرص.

## التشخيصات وOpenTelemetry

التشخيصات هي أحداث مهيكلة قابلة للقراءة آليًا لتشغيلات النماذج وبيانات
القياس الخاصة بتدفق الرسائل (Webhooks، وقوائم الانتظار، وحالة الجلسات). وهي **لا**
تحل محل السجلات — بل تغذي المقاييس وآثار التتبع والمصدّرات. ويتم إصدار الأحداث
داخل العملية سواء قمت بتصديرها أم لا.

هناك سطحان متجاوران:

- **تصدير OpenTelemetry** — إرسال المقاييس وآثار التتبع والسجلات عبر OTLP/HTTP إلى
  أي مجمّع أو واجهة خلفية متوافقة مع OpenTelemetry (Grafana، وDatadog،
  وHoneycomb، وNew Relic، وTempo، وغيرها). وتوجد التهيئة الكاملة، وكتالوج الإشارات،
  وأسماء المقاييس/الامتدادات، ومتغيرات البيئة، ونموذج الخصوصية في صفحة مخصصة:
  [تصدير OpenTelemetry](/ar/gateway/opentelemetry).
- **أعلام التشخيصات** — أعلام سجلات تصحيح مستهدفة توجّه سجلات إضافية إلى
  `logging.file` من دون رفع `logging.level`. وهذه الأعلام غير حساسة لحالة الأحرف
  وتدعم wildcards ‏(`telegram.*`، `*`). قم بتهيئتها تحت `diagnostics.flags`
  أو عبر تجاوز البيئة `OPENCLAW_DIAGNOSTICS=...`. الدليل الكامل:
  [أعلام التشخيصات](/ar/diagnostics/flags).

لتمكين أحداث التشخيصات لـ Plugins أو واجهات الإدخال المخصصة دون تصدير OTLP:

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

أما لتصدير OTLP إلى مجمّع، فراجع [تصدير OpenTelemetry](/ar/gateway/opentelemetry).

## نصائح استكشاف الأخطاء وإصلاحها

- **تعذر الوصول إلى Gateway؟** شغّل `openclaw doctor` أولًا.
- **السجلات فارغة؟** تحقق من أن Gateway قيد التشغيل ويكتب إلى مسار الملف
  الموجود في `logging.file`.
- **تحتاج إلى مزيد من التفاصيل؟** عيّن `logging.level` إلى `debug` أو `trace` ثم أعد المحاولة.

## ذو صلة

- [تصدير OpenTelemetry](/ar/gateway/opentelemetry) — تصدير OTLP/HTTP، وكتالوج المقاييس/الامتدادات، ونموذج الخصوصية
- [أعلام التشخيصات](/ar/diagnostics/flags) — أعلام سجلات التصحيح المستهدفة
- [تفاصيل تسجيل Gateway الداخلية](/ar/gateway/logging) — أنماط سجلات WS، وبادئات الأنظمة الفرعية، والتقاط الطرفية
- [مرجع التهيئة](/ar/gateway/configuration-reference#diagnostics) — مرجع الحقول الكامل لـ `diagnostics.*`
