الانتقال إلى المحتوى الرئيسي

​
الحضور

«الحضور» في 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 (التكرارات متوقعة)