> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# الحضور

# الحضور

«الحضور» في OpenClaw هو عرض خفيف الوزن وبأفضل جهد لـ:

* **Gateway** نفسه، و
* **العملاء المتصلين بـ Gateway** (تطبيق mac، وWebChat، وCLI، إلخ).

يُستخدم الحضور بشكل أساسي لعرض علامة تبويب **Instances** في تطبيق macOS
ولتوفير رؤية سريعة للمشغّل.

## حقول الحضور (ما الذي يظهر)

إدخالات الحضور هي كائنات منظَّمة تحتوي على حقول مثل:

* `instanceId` (اختياري لكنه موصى به بشدة): هوية عميل مستقرة (عادةً `connect.client.instanceId`)
* `host`: اسم مضيف مفهوم للبشر
* `ip`: عنوان IP بأفضل جهد
* `version`: سلسلة إصدار العميل
* `deviceFamily` / `modelIdentifier`: تلميحات عن العتاد
* `mode`: `ui`، `webchat`، `cli`، `backend`، `probe`، `test`، `node`، ...
* `lastInputSeconds`: «عدد الثواني منذ آخر إدخال للمستخدم» (إن كان معروفًا)
* `reason`: `self`، `connect`، `node-connected`، `periodic`، ...
* `ts`: طابع زمني لآخر تحديث (مللي ثانية منذ epoch)

## المنتجون (من أين يأتي الحضور)

تُنتَج إدخالات الحضور من مصادر متعددة ويتم **دمجها**.

### 1. إدخال Gateway الذاتي

يقوم Gateway دائمًا بتهيئة إدخال «ذاتي» عند بدء التشغيل حتى تعرض واجهات
المستخدم مضيف الـ Gateway
حتى قبل اتصال أي عملاء.

### 2. اتصال WebSocket

يبدأ كل عميل WS بطلب `connect`. وعند نجاح المصافحة،
يقوم Gateway بإدراج/تحديث (upsert) إدخال حضور لذلك الاتصال.

#### لماذا لا تظهر أوامر CLI لمرة واحدة

غالبًا ما يتصل CLI لفترة قصيرة لتنفيذ أوامر لمرة واحدة. لتجنب إغراق
قائمة Instances، فإن `client.mode === "cli"` **لا**
يتم تحويله إلى إدخال حضور.

### 3. منارات `system-event`

يمكن للعملاء إرسال منارات دورية أغنى عبر الأسلوب `system-event`. يستخدم تطبيق mac هذا للإبلاغ عن اسم المضيف وعنوان IP و`lastInputSeconds`.

### 4. اتصالات العُقد (الدور: node)

عندما تتصل عُقدة عبر WebSocket الخاص بالـ Gateway باستخدام `role: node`،
يقوم Gateway بإدراج/تحديث إدخال حضور لتلك العُقدة (نفس التدفق مثل
عملاء WS الآخرين).

## قواعد الدمج وإزالة التكرار (لماذا يهم `instanceId`)

تُخزَّن إدخالات الحضور في خريطة واحدة داخل الذاكرة:

* يتم تحديد الإدخالات بواسطة **مفتاح حضور**.
* أفضل مفتاح هو `instanceId` مستقر (من `connect.client.instanceId`) يبقى عبر
  إعادات التشغيل.
* المفاتيح غير حساسة لحالة الأحرف.

إذا أعاد عميل الاتصال دون `instanceId` مستقر،
فقد يظهر كصف **مكرر**.

## مدة الحياة (TTL) والحجم المحدود

ويكون الحضور متعمدا سريعا:

* **TTL:** تتم إزالة الإدخالات الأقدم من 5 دقائق
* **الحد الأقصى للإدخالات:** 200 (يتم إسقاط الأقدم أولًا)

يحافظ ذلك على حداثة القائمة ويتجنب نمو الذاكرة غير المحدود.

## تحذير النفق البعيد/البعيد (الحلبة IPs)

عندما يتصل عميل عبر نفق SSH / إعادة توجيه منفذ محلي،
قد يرى Gateway العنوان البعيد كـ `127.0.0.1`. لتجنب الكتابة فوق عنوان IP جيد أبلغ عنه العميل،
يتم تجاهل عناوين loopback البعيدة.

## المستهلكون

### علامة تبويب Instances في macOS

يعرض تطبيق macOS ناتج `system-presence` ويطبّق مؤشر حالة صغير
(نشط/خامل/قديم) بناءً على عمر آخر تحديث.

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

* لرؤية القائمة الخام، استدعِ `system-presence` مقابل Gateway.
* إذا رأيت تكرارات:
  * أكّد أن العملاء يرسلون `client.instanceId` مستقرًا في المصافحة
  * أكّد أن المنارات الدورية تستخدم نفس `instanceId`
  * تحقّق مما إذا كان الإدخال المشتق من الاتصال يفتقد `instanceId` (التكرارات متوقعة)