---
read_when:
    - تحتاج إلى نظرة عامة مناسبة للمبتدئين حول تسجيل OpenClaw
    - تريد تكوين مستويات التسجيل أو التنسيقات أو حجب البيانات
    - أنت بصدد استكشاف الأخطاء وإصلاحها وتحتاج إلى العثور على السجلات بسرعة
summary: سجلات الملفات، ومخرجات وحدة التحكم، ومتابعة السجلات عبر CLI، وعلامة تبويب السجلات في واجهة التحكم
title: تسجيل السجلات
x-i18n:
    generated_at: "2026-05-11T20:36:15Z"
    model: gpt-5.5
    provider: openai
    source_hash: 49b28755998bbe667dd986ae8440d9006d03b0704679bb6d64b5a148a25fc50e
    source_path: logging.md
    workflow: 16
---

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

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

يعرض تبويب **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` الصريحة
هذا الرجوع الاحتياطي.

إذا تعذر الوصول إلى 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 المرقمة في العمل.

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

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

سجلات وحدة التحكم **مدركة لـ 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`.

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

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

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

تتدفق سجلات دورة حياة Talk أيضًا إلى سجلات OTLP عند تمكين تصدير سجلات OpenTelemetry،
باستخدام السمات المحدودة نفسها مثل سجلات الملفات.

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

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

- `requestPayloadBytes`: حجم حمولة طلب النموذج النهائية ببايتات UTF-8
- `responseStreamBytes`: حجم أحداث استجابة النموذج المتدفقة ببايتات UTF-8
- `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).

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