สถานะออนไลน์¶

“presence” ของ OpenClaw คือมุมมองแบบเบาและพยายามให้ดีที่สุดของ:

• ตัว Gateway เอง และ
• ไคลเอนต์ที่เชื่อมต่อกับ Gateway (แอปmacOS, 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. รายการ self ของ Gateway¶

Gateway จะใส่รายการ “self” ตั้งแต่เริ่มทำงาน เพื่อให้ UI แสดงโฮสต์ของเกตเวย์ได้ แม้ยังไม่มีไคลเอนต์เชื่อมต่อ

2. การเชื่อมต่อ WebSocket¶

ไคลเอนต์ WS ทุกตัวเริ่มด้วยคำขอ connect เมื่อแฮนด์เชคสำเร็จ Gateway จะ upsert รายการ presence สำหรับการเชื่อมต่อนั้น 18. เมื่อทำการแฮนด์เชคสำเร็จ Gateway จะทำการ upsert รายการ presence สำหรับการเชื่อมต่อนั้น

เหตุผลที่คำสั่ง CLI แบบครั้งเดียวไม่แสดง¶

19. CLI มักเชื่อมต่อเพื่อคำสั่งสั้น ๆ แบบครั้งเดียว CLI มักเชื่อมต่อสั้นๆเพื่อรันคำสั่งแบบครั้งเดียว เพื่อหลีกเลี่ยงการรบกวนรายการ Instances จึง ไม่ นำ client.mode === "cli" มาสร้างเป็นรายการ presence

3. บีคอน system-event¶

20. ไคลเอนต์สามารถส่งบีคอนตามรอบที่มีข้อมูลมากขึ้นผ่านเมธอด system-event ไคลเอนต์สามารถส่งบีคอนตามช่วงเวลาที่มีข้อมูลมากขึ้นผ่านเมธอด system-event แอปmacOS ใช้สิ่งนี้เพื่อรายงานชื่อโฮสต์ IP และ lastInputSeconds

4. การเชื่อมต่อของโหนด (บทบาท: node)¶

เมื่อโหนดเชื่อมต่อผ่าน Gateway WebSocket ด้วย role: node Gateway จะ upsert รายการ presence สำหรับโหนดนั้น (โฟลว์เดียวกับไคลเอนต์ WS อื่นๆ)

กฎการรวมและกำจัดซ้ำ (เหตุใด instanceId จึงสำคัญ)¶

รายการ presence ถูกเก็บในแมปในหน่วยความจำเดียว:

• รายการถูกคีย์ด้วย presence key
• คีย์ที่ดีที่สุดคือตัว instanceId ที่เสถียร (จาก connect.client.instanceId) ซึ่งอยู่ข้ามการรีสตาร์ตได้
• 21. คีย์ไม่แยกตัวพิมพ์เล็ก/ใหญ่

หากไคลเอนต์เชื่อมต่อใหม่โดยไม่มี instanceId ที่เสถียร อาจแสดงเป็นแถว ซ้ำ

TTL และขนาดที่จำกัด¶

22. Presence ถูกออกแบบให้เป็นแบบชั่วคราวโดยตั้งใจ:

• TTL: รายการที่เก่ากว่า 5 นาทีจะถูกลบออก
• จำนวนสูงสุด: 200 (ลบรายการที่เก่าที่สุดก่อน)

สิ่งนี้ช่วยให้รายการสดใหม่และหลีกเลี่ยงการใช้หน่วยความจำไม่จำกัด

ข้อควรระวังรีโมต/อุโมงค์ (IP loopback)¶

เมื่อไคลเอนต์เชื่อมต่อผ่านอุโมงค์SSH/การฟอร์เวิร์ดพอร์ตภายในเครื่อง Gateway อาจเห็น ที่อยู่รีโมตเป็น 127.0.0.1 เพื่อหลีกเลี่ยงการเขียนทับ IP ที่ไคลเอนต์รายงานมาอย่างถูกต้อง ที่อยู่รีโมตแบบ loopback จะถูกเพิกเฉย 23. เพื่อหลีกเลี่ยงการเขียนทับ IP ที่ไคลเอนต์รายงานมาอย่างถูกต้อง ที่อยู่รีโมตแบบ loopback จะถูกละเว้น

24. ผู้ใช้งาน¶

แท็บ Instances ของ macOS¶

แอปmacOS แสดงผลลัพธ์ของ system-presence และใช้ตัวบ่งชี้สถานะเล็กน้อย (Active/Idle/Stale) ตามอายุของการอัปเดตล่าสุด

เคล็ดลับการดีบัก¶

• หากต้องการดูรายการดิบ ให้เรียก system-presence กับ Gateway
• หากพบรายการซ้ำ:
• ตรวจสอบว่าไคลเอนต์ส่ง client.instanceId ที่เสถียรในขั้นตอนแฮนด์เชค
• ตรวจสอบว่าบีคอนตามช่วงเวลาใช้ instanceId เดียวกัน
• ตรวจสอบว่ารายการที่ได้จากการเชื่อมต่อขาด instanceId หรือไม่ (การซ้ำถือว่าเกิดขึ้นได้)