---
read_when:
    - تحتاج إلى نظرة عامة مناسبة للمبتدئين حول تسجيل OpenClaw
    - تريد تكوين مستويات السجلات أو تنسيقاتها أو تنقيحها
    - أنت تستكشف الأخطاء وتحتاج إلى العثور على السجلات بسرعة
summary: سجلات الملفات، ومخرجات وحدة التحكم، ومتابعة السجلات عبر CLI، وعلامة تبويب السجلات في واجهة التحكم
title: تسجيل السجلات
x-i18n:
    generated_at: "2026-06-27T17:53:58Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: caf2780dfeeaf29f4ee94429894a03422b211a4414e63062642d1134f38b6b3f
    source_path: logging.md
    workflow: 16
---

يحتوي OpenClaw على سطحين رئيسيين للسجلات:

- **سجلات الملفات** (أسطر JSON) التي يكتبها Gateway.
- **مخرجات وحدة التحكم** المعروضة في الطرفيات وواجهة تصحيح أخطاء Gateway.

يتتبع تبويب **Logs** في واجهة Control UI سجل ملف 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` الصريحة
هذا الرجوع الاحتياطي. يكون `openclaw logs --follow` أكثر صرامة: على Linux يستخدم سجل
Gateway النشط الخاص بـ user-systemd حسب PID عند توفره، وإلا يواصل إعادة محاولة
Gateway المباشر بدلًا من تتبع ملف جانبي قديم محتملًا.

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

```bash
openclaw doctor
```

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

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

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

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

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

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

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

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

تتضمن سجلات JSONL الخاصة بالملفات أيضًا حقولًا علوية قابلة للتصفية آليًا عند
توفرها:

- `hostname`: اسم مضيف Gateway.
- `message`: نص رسالة السجل المسطح للبحث النصي الكامل.
- `agent_id`: معرف الوكيل النشط عندما تحمل استدعاء السجل سياق وكيل.
- `session_id`: معرف/مفتاح الجلسة النشطة عندما تحمل استدعاء السجل سياق جلسة.
- `channel`: القناة النشطة عندما تحمل استدعاء السجل سياق قناة.

يحافظ OpenClaw على وسيطات السجل المنظمة الأصلية بجانب هذه الحقول
حتى تستمر المحللات الحالية التي تقرأ مفاتيح وسيطات tslog المرقمة في العمل.

تصدر أنشطة الكلام، والصوت في الوقت الحقيقي، والغرف المُدارة سجلات دورة حياة محدودة
عبر مسار سجل الملفات نفسه. تتضمن هذه السجلات نوع الحدث،
والوضع، والنقل، والمزود، وقياسات الحجم/التوقيت عند توفرها، لكنها تحذف
نص النسخ، وحمولات الصوت، ومعرفات الدور، ومعرفات المكالمة، ومعرفات عناصر المزود.

### مخرجات وحدة التحكم

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

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

يتحكم `logging.consoleStyle` في تنسيق وحدة التحكم.

### سجلات Gateway WebSocket

لدى `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؛ ولا يغير
مستويات سجل الملفات.

### تشخيصات نقل النموذج المستهدفة

عند تصحيح استدعاءات المزود، استخدم أعلام البيئة المستهدفة بدلًا من رفع
كل السجلات إلى `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`: تضمين ملخص محدود لحمولة الطلب
  في سجلات طلب النموذج.
- `OPENCLAW_DEBUG_MODEL_PAYLOAD=tools`: تضمين كل أسماء الأدوات المواجهة للنموذج في
  ملخص الحمولة.
- `OPENCLAW_DEBUG_MODEL_PAYLOAD=full-redacted`: تضمين لقطة حمولة JSON
  منقحة ومحدودة. استخدمه أثناء التصحيح فقط؛ يتم تنقيح الأسرار لكن قد تبقى
  المطالبات ونص الرسائل موجودة.
- `OPENCLAW_DEBUG_SSE=events`: إصدار توقيت أول حدث واكتمال التدفق.
- `OPENCLAW_DEBUG_SSE=peek`: إصدار أول خمس حمولات أحداث SSE منقحة
  أيضًا، مع حد لكل حدث.
- `OPENCLAW_DEBUG_CODE_MODE=1`: إصدار تشخيصات سطح النموذج في وضع الكود،
  بما في ذلك عندما تُخفى أدوات المزود الأصلية لأن وضع الكود يملك
  سطح الأدوات.

تسجل هذه الأعلام عبر تسجيل OpenClaw العادي، لذا يعرضها `openclaw logs --follow`
وتبويب Logs في Control UI. بدون الأعلام، تبقى التشخيصات نفسها
متاحة عند مستوى `debug`.

تُصدر بيانات تعريف بداية واستجابة `[model-fetch]` (المزود، API، النموذج، الحالة،
زمن الاستجابة، وحقول الطلب مثل الطريقة، وURL، والمهلة، والوكيل، والسياسة)
دائمًا عند مستوى `info` بغض النظر عن
`OPENCLAW_DEBUG_MODEL_TRANSPORT`، لذا تكون أساسيات نظافة نقل النموذج مرئية
دون أعلام التصحيح.

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

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

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

تتدفق سجلات دورة حياة الكلام أيضًا إلى تصدير سجلات diagnostics-otel عند
تمكين تصدير سجلات OpenTelemetry، باستخدام السمات المحدودة نفسها كسجلات الملفات.
اضبط `diagnostics.otel.logsExporter` لاختيار OTLP، أو stdout JSONL، أو
كلا المصبين.

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

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

- `requestPayloadBytes`: حجم حمولة طلب النموذج النهائية بالبايت وفق UTF-8
- `responseStreamBytes`: حجم حمولات أجزاء استجابة النموذج المتدفقة بالبايت وفق UTF-8.
  تُحتسب أحداث النص عالية التكرار، والتفكير، وفروق استدعاءات الأدوات
  ببايتات `delta` التزايدية فقط بدلًا من لقطات `partial` الكاملة.
- `timeToFirstByteMs`: الوقت المنقضي قبل أول حدث استجابة متدفق
- `durationMs`: المدة الإجمالية لاستدعاء النموذج

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

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

`logging.consoleStyle`:

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

### التنقيح

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

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

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

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

يعطل `logging.redactSensitive: "off"` سياسة السجل/النسخ العامة هذه فقط.
لا يزال OpenClaw ينقح حمولات حدود السلامة التي يمكن عرضها لعملاء UI،
أو حزم الدعم، أو مراقبي التشخيصات، أو مطالبات الموافقة، أو أدوات الوكيل.
تشمل الأمثلة أحداث استدعاء أدوات Control UI، ومخرجات `sessions_history`،
وصادرات دعم التشخيصات، وملاحظات أخطاء المزود، وعرض أمر موافقة exec،
وسجلات بروتوكول Gateway WebSocket. يمكن أن تضيف `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).

لتمكين أحداث التشخيصات لـ Plugin أو مصبات مخصصة دون تصدير 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.*`