موجودگی¶

OpenClaw کی “presence” ایک ہلکی پھلکی، بہترین کوشش پر مبنی جھلک ہے:

• خود Gateway کی، اور
• Gateway سے منسلک کلائنٹس کی (mac ایپ، WebChat، CLI، وغیرہ)

Presence بنیادی طور پر macOS ایپ کے Instances ٹیب کو رینڈر کرنے اور آپریٹر کو فوری مرئیّت فراہم کرنے کے لیے استعمال ہوتی ہے۔

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 کے بعد سے ms)

Producers (presence کہاں سے آتی ہے)¶

Presence اندراجات متعدد ذرائع سے تیار ہوتی ہیں اور ضم کی جاتی ہیں۔

1. Gateway کی خود اندراج¶

Gateway آغاز پر ہمیشہ ایک “self” اندراج شامل کرتا ہے تاکہ کسی بھی کلائنٹ کے کنیکٹ ہونے سے پہلے ہی UIs میں گیٹ وے ہوسٹ دکھائی دے۔

2. WebSocket کنیکٹ¶

22. کامیاب handshake پر Gateway اس کنکشن کے لیے ایک presence انٹری upsert کرتا ہے۔ 23. CLI اکثر مختصر، ایک بار کے کمانڈز کے لیے کنیکٹ ہوتا ہے۔

ایک وقتی CLI کمانڈز کیوں نظر نہیں آتیں¶

24. Instances فہرست میں اسپام سے بچنے کے لیے client.mode === "cli" کو presence انٹری میں تبدیل نہیں کیا جاتا۔ 25. کلائنٹس system-event طریقہ کے ذریعے زیادہ تفصیلی متواتر beacons بھیج سکتے ہیں۔

3. system-event بیکنز¶

26. mac ایپ اس کا استعمال host name، IP، اور lastInputSeconds رپورٹ کرنے کے لیے کرتی ہے۔ 27. جب کوئی کلائنٹ SSH ٹنل / لوکل پورٹ فارورڈ کے ذریعے کنیکٹ ہو تو Gateway ریموٹ ایڈریس کو 127.0.0.1 کے طور پر دیکھ سکتا ہے۔

4. نوڈ کنیکشنز (کردار: node)¶

جب کوئی نوڈ role: node کے ساتھ Gateway WebSocket پر کنیکٹ ہوتا ہے تو Gateway اس نوڈ کے لیے presence اندراج کو upsert کرتا ہے (وہی عمل جو دیگر WS کلائنٹس کے لیے ہے)۔

Merge + dedupe قواعد (کیوں instanceId اہم ہے)¶

Presence اندراجات ایک واحد in‑memory نقشے میں محفوظ ہوتی ہیں:

• اندراجات ایک presence key کے ذریعے کیڈ کی جاتی ہیں۔
• بہترین key ایک مستحکم instanceId ہے (جو connect.client.instanceId سے آتا ہے) جو ری اسٹارٹس کے بعد بھی برقرار رہتا ہے۔
• keys حروف کے بڑے/چھوٹے فرق کے بغیر ہوتی ہیں۔

اگر کوئی کلائنٹ مستحکم instanceId کے بغیر دوبارہ کنیکٹ کرے تو وہ ڈپلیکیٹ قطار کے طور پر نظر آ سکتا ہے۔

TTL اور محدود سائز¶

Presence دانستہ طور پر عارضی ہوتی ہے:

• TTL: 5 منٹ سے پرانے اندراجات حذف کر دیے جاتے ہیں
• زیادہ سے زیادہ اندراجات: 200 (قدیم ترین پہلے خارج)

یہ فہرست کو تازہ رکھتا ہے اور غیر محدود میموری بڑھوتری سے بچاتا ہے۔

Remote/سرنگ احتیاط (loopback IPs)¶

28. کسی درست کلائنٹ‑رپورٹڈ IP کو اووررائٹ کرنے سے بچنے کے لیے loopback ریموٹ ایڈریسز کو نظرانداز کیا جاتا ہے۔ 27. کسی درست کلائنٹ‑رپورٹڈ IP کو اوور رائٹ ہونے سے بچانے کے لیے، لوپ بیک ریموٹ ایڈریسز کو نظر انداز کیا جاتا ہے۔

صارفین¶

macOS Instances ٹیب¶

macOS ایپ system-presence کے آؤٹ پٹ کو رینڈر کرتی ہے اور آخری اپ ڈیٹ کی عمر کی بنیاد پر ایک چھوٹا اسٹیٹس اشارہ (Active/Idle/Stale) لاگو کرتی ہے۔

خرابیوں کے ازالے کے نکات¶

• خام فہرست دیکھنے کے لیے Gateway کے خلاف system-presence کال کریں۔
• اگر آپ کو ڈپلیکیٹس نظر آئیں:
• تصدیق کریں کہ کلائنٹس ہینڈ شیک میں ایک مستحکم client.instanceId بھیجتے ہیں
• تصدیق کریں کہ دورانیہ وار بیکنز وہی instanceId استعمال کرتے ہیں
• دیکھیں کہ آیا کنیکشن‑سے ماخوذ اندراج میں instanceId موجود نہیں (اس صورت میں ڈپلیکیٹس متوقع ہیں)