الحضور

يُعد «الحضور» في OpenClaw عرضًا خفيفًا يعتمد على أفضل جهد لكل من:

• Gateway نفسه، و
• العملاء المتصلين بـ Gateway (تطبيق mac، وWebChat، وCLI، وما إلى ذلك)

يُستخدم الحضور أساسًا لعرض علامة تبويب المثيلات في تطبيق 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: طابع وقت آخر تحديث (بالملي ثانية منذ الحقبة)

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

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

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

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

# 2) اتصال WebSocket

يبدأ كل عميل WS بطلب connect. عند نجاح المصافحة، يُدرج Gateway إدخال حضور أو يحدّثه لذلك الاتصال.

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

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

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

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

# 4) اتصالات Node (الدور: node)

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

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

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

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

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

# مدة البقاء والحجم المحدود

الحضور مؤقت عمدًا:

• مدة البقاء: تُزال الإدخالات الأقدم من 5 دقائق
• الحد الأقصى للإدخالات: 200 (تُسقط الأقدم أولًا)

يبقي ذلك القائمة حديثة ويتجنب نمو الذاكرة دون حدود.

# تنبيه بخصوص الاتصال البعيد/النفق (عناوين IP الخاصة بـ local loopback)

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

# المستهلكون

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

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

# نصائح تصحيح الأخطاء

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

# ذو صلة