---
read_when:
    - تحتاج إلى نظرة عامة مناسبة للمبتدئين حول تسجيل السجلات في OpenClaw
    - تريد تكوين مستويات السجلات أو تنسيقاتها أو تنقيحها
    - أنت بصدد استكشاف الأخطاء وإصلاحها وتحتاج إلى العثور على السجلات بسرعة
summary: سجلات الملفات، ومخرجات وحدة التحكم، ومتابعة CLI، وعلامة تبويب السجلات في واجهة التحكم
title: تسجيل الأحداث
x-i18n:
    generated_at: "2026-05-01T07:40:45Z"
    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 ميغابايت).
يحتفظ 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 الضمني عبر local loopback الاقتران، أو أغلق أثناء الاتصال،
أو انتهت مهلته قبل أن يجيب `logs.tail`، فإن `openclaw logs` يعود تلقائيًا إلى
سجل ملف Gateway المضبوط. لا تستخدم أهداف `--url` الصريحة
هذا الرجوع الاحتياطي.

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

```bash
openclaw doctor
```

### واجهة التحكم (الويب)

يتابع تبويب **السجلات** في واجهة التحكم الملف نفسه باستخدام `logs.tail`.
راجع [/web/control-ui](/ar/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** ومنسقة لقابلية القراءة:

- بادئات الأنظمة الفرعية (مثل `gateway/channels/whatsapp`)
- تلوين المستويات (info/warn/error)
- وضع مضغوط أو 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؛ ولا يغير
مستويات سجلات الملفات.

### ربط التتبعات

سجلات الملفات هي JSONL. عندما يحمل استدعاء سجل سياق تتبع تشخيصي صالحًا،
يكتب OpenClaw حقول التتبع كمفاتيح JSON علوية (`traceId` و`spanId` و
`parentSpanId` و`traceFlags`) كي تتمكن معالجات السجلات الخارجية من ربط السطر
بامتدادات OTEL وانتشار `traceparent` لدى المزود.

تنشئ طلبات HTTP الخاصة بـ Gateway وإطارات WebSocket الخاصة بـ Gateway نطاق تتبع طلب داخليًا.
ترث السجلات والأحداث التشخيصية الصادرة داخل ذلك النطاق غير المتزامن
تتبع الطلب عندما لا تمرر سياق تتبع صريحًا. تصبح تتبعات تشغيل الوكيل و
استدعاء النموذج أبناء لتتبع الطلب النشط، بحيث يمكن ربط السجلات المحلية،
واللقطات التشخيصية، وامتدادات OTEL، وترويسات `traceparent` الموثوقة للمزود
بواسطة `traceId` دون تسجيل محتوى الطلب أو النموذج الخام.

### حجم استدعاء النموذج وتوقيته

تسجل تشخيصات استدعاء النموذج قياسات محدودة للطلب/الاستجابة دون
التقاط محتوى الموجه أو الاستجابة الخام:

- `requestPayloadBytes`: حجم حمولة طلب النموذج النهائية بالبايت وفق UTF-8
- `responseStreamBytes`: حجم أحداث استجابة النموذج المتدفقة بالبايت وفق UTF-8
- `timeToFirstByteMs`: الوقت المنقضي قبل أول حدث استجابة متدفق
- `durationMs`: مدة استدعاء النموذج الإجمالية

تتوفر هذه الحقول للقطات التشخيصية، وخطافات Plugin لاستدعاء النموذج، و
امتدادات/مقاييس OTEL لاستدعاء النموذج عند تمكين تصدير التشخيصات.

### أنماط وحدة التحكم

`logging.consoleStyle`:

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

### التنقيح

يمكن لـ OpenClaw تنقيح الرموز الحساسة قبل وصولها إلى مخرجات وحدة التحكم، أو سجلات الملفات،
أو سجلات OTLP، أو نصوص محاضر الجلسات المستمرة، أو حمولات أحداث أدوات
واجهة التحكم (وسائط بدء الأداة، وحمولات النتائج الجزئية/النهائية، ومخرجات
exec المشتقة، وملخصات التصحيحات):

- `logging.redactSensitive`: `off` | `tools` (القيمة الافتراضية: `tools`)
- `logging.redactPatterns`: قائمة بسلاسل regex لتجاوز المجموعة الافتراضية. تطبق الأنماط المخصصة فوق الافتراضيات المضمنة لحمولات أدوات واجهة التحكم، لذا فإن إضافة نمط لا تضعف أبدًا تنقيح القيم التي تلتقطها الافتراضيات بالفعل.

تبقى سجلات الملفات ومحاضر الجلسات بصيغة JSONL، لكن قيم الأسرار المطابقة
تُحجب قبل كتابة السطر أو الرسالة إلى القرص. التنقيح قائم على أفضل جهد:
ينطبق على محتوى الرسائل الحاملة للنصوص وسلاسل السجلات، وليس على كل
معرف أو حقل حمولة ثنائي.

تغطي الافتراضيات المضمنة بيانات اعتماد API الشائعة وأسماء حقول بيانات اعتماد
الدفع مثل رقم البطاقة، وCVC/CVV، ورمز الدفع المشترك، وبيانات اعتماد الدفع
عندما تظهر كحقول JSON، أو معاملات URL، أو أعلام CLI، أو إسنادات.

يعطل `logging.redactSensitive: "off"` سياسة السجلات/المحاضر العامة هذه فقط.
ما زال OpenClaw ينقح حمولات حدود السلامة التي يمكن عرضها لعملاء واجهة UI،
أو حزم الدعم، أو مراقبي التشخيصات، أو مطالبات الموافقة، أو أدوات الوكيل.
تشمل الأمثلة أحداث استدعاء الأدوات في واجهة التحكم، ومخرجات `sessions_history`،
وتصديرات دعم التشخيصات، وملاحظات أخطاء المزود، وعرض أمر موافقة exec،
وسجلات بروتوكول WebSocket الخاصة بـ Gateway. ما تزال `logging.redactPatterns`
المخصصة قادرة على إضافة أنماط خاصة بالمشروع على تلك الأسطح.

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

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

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

- **تصدير OpenTelemetry** — إرسال المقاييس، والتتبعات، والسجلات عبر OTLP/HTTP إلى
  أي جامع أو خلفية متوافقة مع OpenTelemetry (Grafana، Datadog،
  Honeycomb، New Relic، Tempo، إلخ). توجد الإعدادات الكاملة، وفهرس الإشارات،
  وأسماء المقاييس/الامتدادات، ومتغيرات البيئة، ونموذج الخصوصية في صفحة مخصصة:
  [تصدير OpenTelemetry](/ar/gateway/opentelemetry).
- **أعلام التشخيصات** — أعلام سجلات تصحيح موجهة توجه سجلات إضافية إلى
  `logging.file` دون رفع `logging.level`. الأعلام غير حساسة لحالة الأحرف
  وتدعم أحرف البدل (`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.*`
