---
read_when:
    - تغيير مخرجات التسجيل أو تنسيقاته
    - استكشاف أخطاء مخرجات CLI أو البوابة وإصلاحها
summary: أسطح التسجيل، وسجلات الملفات، وأنماط سجلات WS، وتنسيق وحدة التحكم
title: تسجيل Gateway
x-i18n:
    generated_at: "2026-04-05T12:43:09Z"
    model: gpt-5.4
    provider: openai
    source_hash: 465fe66ae6a3bc844e75d3898aed15b3371481c4fe89ede40e5a9377e19bb74c
    source_path: gateway/logging.md
    workflow: 15
---

# التسجيل

للحصول على نظرة عامة موجهة للمستخدم (CLI + Control UI + config)، راجع [/logging](/logging).

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

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

## المسجل المعتمد على الملفات

- يوجد ملف السجل الدوّار الافتراضي ضمن `/tmp/openclaw/` (ملف واحد لكل يوم): `openclaw-YYYY-MM-DD.log`
  - يستخدم التاريخ المنطقة الزمنية المحلية لمضيف البوابة.
- يمكن إعداد مسار ملف السجل والمستوى عبر `~/.openclaw/openclaw.json`:
  - `logging.file`
  - `logging.level`

صيغة الملف هي كائن JSON واحد في كل سطر.

يقوم تبويب Logs في Control UI بتتبع هذا الملف عبر البوابة (`logs.tail`).
ويمكن لـ CLI فعل الشيء نفسه:

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

**Verbose مقابل مستويات السجل**

- يتم التحكم في **سجلات الملفات** حصريًا عبر `logging.level`.
- يؤثر `--verbose` فقط على **درجة تفصيل وحدة التحكم** (ونمط سجل WS)؛ ولا **يرفع**
  مستوى سجل الملف.
- لالتقاط التفاصيل الخاصة بـ verbose فقط في سجلات الملفات، اضبط `logging.level` على `debug` أو
  `trace`.

## التقاط وحدة التحكم

يلتقط CLI استدعاءات `console.log/info/warn/error/debug/trace` ويكتبها إلى سجلات الملفات،
مع الاستمرار في طباعتها إلى stdout/stderr.

يمكنك ضبط درجة تفصيل وحدة التحكم بشكل مستقل عبر:

- `logging.consoleLevel` (الافتراضي `info`)
- `logging.consoleStyle` (`pretty` | `compact` | `json`)

## حجب ملخصات الأدوات

يمكن لملخصات الأدوات المفصلة (مثل `🛠️ Exec: ...`) إخفاء الرموز الحساسة قبل وصولها إلى
تدفق وحدة التحكم. وهذا **خاص بالأدوات فقط** ولا يغيّر سجلات الملفات.

- `logging.redactSensitive`: ‏`off` | `tools` (الافتراضي: `tools`)
- `logging.redactPatterns`: مصفوفة من سلاسل regex (تتجاوز القيم الافتراضية)
  - استخدم سلاسل regex خام (مع `gi` تلقائيًا)، أو `/pattern/flags` إذا كنت بحاجة إلى رايات مخصصة.
  - يتم حجب المطابقات عبر الاحتفاظ بأول 6 + آخر 4 أحرف (عندما يكون الطول >= 18)، وإلا `***`.
  - تغطي القيم الافتراضية تعيينات المفاتيح الشائعة، وعلامات CLI، وحقول JSON، وترويسات bearer، وكتل PEM، وبادئات الرموز الشائعة.

## سجلات Gateway WebSocket

تطبع البوابة سجلات بروتوكول WebSocket في وضعين:

- **الوضع العادي (من دون `--verbose`)**: تتم طباعة نتائج RPC "المهمة" فقط:
  - الأخطاء (`ok=false`)
  - الاستدعاءات البطيئة (الحد الافتراضي: `>= 50ms`)
  - أخطاء التحليل
- **الوضع المفصل (`--verbose`)**: يطبع كل حركة WS للطلبات/الاستجابات.

### نمط سجل WS

يدعم `openclaw 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`
- **بادئات أنظمة فرعية مختصرة**: تُسقط `gateway/` و`channels/` في البداية، وتحتفظ بآخر مقطعين (مثل `whatsapp/outbound`)
- **مسجلات فرعية حسب النظام الفرعي** (بادئة تلقائية + حقل منظم `{ subsystem }`)
- **`logRaw()`** لمخرجات QR/UX (من دون بادئة، ومن دون تنسيق)
- **أنماط وحدة التحكم** (مثل `pretty | compact | json`)
- **مستوى سجل وحدة التحكم** منفصل عن مستوى سجل الملف (يحافظ الملف على التفاصيل الكاملة عندما يتم ضبط `logging.level` على `debug`/`trace`)
- **تُسجل أجسام رسائل WhatsApp** عند مستوى `debug` (استخدم `--verbose` لرؤيتها)

يحافظ هذا على استقرار سجلات الملفات الحالية مع جعل المخرجات التفاعلية قابلة للمسح.
