---
read_when:
    - تصحيح تبويب Instances
    - التحقيق في صفوف المثيلات المكررة أو القديمة
    - تغيير إشارات WS connect أو system-event الخاصة بالبوابة
summary: كيفية إنتاج إدخالات Presence في OpenClaw ودمجها وعرضها
title: Presence
x-i18n:
    generated_at: "2026-04-05T12:40:57Z"
    model: gpt-5.4
    provider: openai
    source_hash: a004a1f87be08699c1b2cba97cad8678ce5e27baa425f59eaa18006fdcff26e7
    source_path: concepts/presence.md
    workflow: 15
---

# Presence

يشير "Presence" في OpenClaw إلى عرض خفيف وبأفضل جهد لـ:

- **البوابة** نفسها، و
- **العملاء المتصلين بالبوابة** (تطبيق mac، وWebChat، وCLI، وغير ذلك)

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

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

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

- `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)

## الجهات المنتجة (من أين يأتي Presence)

تنتج إدخالات Presence من مصادر متعددة ويتم **دمجها**.

### 1) إدخال البوابة الذاتي

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

### 2) اتصال WebSocket

يبدأ كل عميل WS بطلب `connect`. وعند نجاح المصافحة، تقوم
البوابة بعملية upsert لإدخال Presence لذلك الاتصال.

#### لماذا لا تظهر أوامر CLI ذات التنفيذ الواحد

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

### 3) إشارات `system-event`

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

### 4) اتصالات العقد (role: node)

عندما تتصل عقدة عبر Gateway WebSocket مع `role: node`، تقوم البوابة
بعملية upsert لإدخال Presence لتلك العقدة (التدفق نفسه مثل عملاء WS الآخرين).

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

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

- تُفهرس الإدخالات بواسطة **مفتاح Presence**.
- أفضل مفتاح هو `instanceId` ثابت (من `connect.client.instanceId`) يبقى ثابتًا عبر عمليات إعادة التشغيل.
- لا تميّز المفاتيح بين الأحرف الكبيرة والصغيرة.

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

## TTL والحجم المحدود

Presence مؤقت بطبيعته عمدًا:

- **TTL:** يتم تقليم الإدخالات الأقدم من 5 دقائق
- **الحد الأقصى للإدخالات:** 200 (تُحذف الأقدم أولًا)

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

## ملاحظة خاصة بالوصول البعيد/الأنفاق (عناوين IP الخاصة بالـ loopback)

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

## الجهات المستهلكة

### تبويب Instances في macOS

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

## نصائح التصحيح

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