การแสดงสถานะ

OpenClaw "presence" เป็นมุมมองแบบเบาและพยายามให้ดีที่สุดของ:

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

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

# 2) การเชื่อมต่อ WebSocket

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

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

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

# 3) beacon system-event

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

# 4) การเชื่อมต่อของ Node (role: node)

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

# กฎการรวม + การลบรายการซ้ำ (เหตุผลที่ instanceId สำคัญ)

รายการ Presence ถูกเก็บไว้ในแผนที่ในหน่วยความจำชุดเดียว:

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

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

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

Presence มีลักษณะชั่วคราวโดยตั้งใจ:

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

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

# ข้อควรระวังเกี่ยวกับรีโมต/ทันเนล (IP แบบ loopback)

เมื่อไคลเอนต์เชื่อมต่อผ่าน SSH tunnel / local port forward Gateway อาจ เห็นที่อยู่ระยะไกลเป็น 127.0.0.1 เพื่อหลีกเลี่ยงการเขียนทับ IP ที่ไคลเอนต์รายงานมาอย่างถูกต้อง ที่อยู่ระยะไกลแบบ loopback จะถูกละเว้น

# ผู้บริโภคข้อมูล

# แท็บ Instances ของ macOS

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

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

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

# ที่เกี่ยวข้อง