​

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 (في هذه الحالة يكون التكرار متوقعًا)