การค้นพบและการรับส่งข้อมูล

OpenClaw มีปัญหาที่แตกต่างกันสองอย่างซึ่งดูคล้ายกันจากภายนอก:

1. การควบคุมระยะไกลของโอเปอเรเตอร์: แอปแถบเมนู macOS ที่ควบคุม Gateway ที่ทำงานอยู่ที่อื่น
2. การจับคู่ Node: iOS/Android (และ Node ในอนาคต) ค้นหา Gateway และจับคู่อย่างปลอดภัย

เป้าหมายของการออกแบบคือเก็บการค้นพบ/การประกาศบนเครือข่ายทั้งหมดไว้ใน Node Gateway (openclaw gateway) และให้ไคลเอนต์ (แอป Mac, iOS) เป็นผู้บริโภค

# คำศัพท์

• Gateway: กระบวนการ Gateway ที่ทำงานต่อเนื่องเพียงหนึ่งเดียวซึ่งเป็นเจ้าของสถานะ (เซสชัน, การจับคู่, รีจิสทรีของ Node) และรันช่องทางต่าง ๆ การตั้งค่าส่วนใหญ่ใช้หนึ่งตัวต่อโฮสต์; การตั้งค่าหลาย Gateway แบบแยกกันก็ทำได้
• Gateway WS (control plane): ปลายทาง WebSocket บน 127.0.0.1:18789 ตามค่าเริ่มต้น; สามารถผูกกับ LAN/tailnet ผ่าน gateway.bind ได้
• การขนส่ง Direct WS: ปลายทาง Gateway WS ที่เปิดให้ LAN/tailnet เข้าถึงได้ (ไม่มี SSH)
• การขนส่ง SSH (ทางสำรอง): การควบคุมระยะไกลโดยส่งต่อ 127.0.0.1:18789 ผ่าน SSH
• บริดจ์ TCP แบบเดิม (นำออกแล้ว): การขนส่ง Node รุ่นเก่า (ดู โปรโตคอล Bridge); ไม่ถูกประกาศสำหรับ การค้นพบอีกต่อไปและไม่เป็นส่วนหนึ่งของบิลด์ปัจจุบันอีกต่อไป

รายละเอียดโปรโตคอล:

• โปรโตคอล Gateway
• โปรโตคอล Bridge (เดิม)

# เหตุผลที่เราคงไว้ทั้งแบบตรงและ SSH

• Direct WS ให้ประสบการณ์ผู้ใช้ที่ดีที่สุดบนเครือข่ายเดียวกันและภายใน tailnet:
  • ค้นพบอัตโนมัติบน LAN ผ่าน Bonjour
  • โทเค็นการจับคู่ + ACLs ที่ Gateway เป็นเจ้าของ
  • ไม่ต้องมีสิทธิ์เข้าถึงเชลล์; พื้นผิวโปรโตคอลสามารถคงให้แน่นและตรวจสอบได้
• SSH ยังคงเป็นทางสำรองสากล:
  • ใช้งานได้ทุกที่ที่คุณมีสิทธิ์ SSH (แม้ข้ามเครือข่ายที่ไม่เกี่ยวข้องกัน)
  • ทนต่อปัญหา multicast/mDNS
  • ไม่ต้องมีพอร์ตขาเข้าใหม่ นอกจาก SSH

# อินพุตการค้นพบ (ไคลเอนต์รู้ตำแหน่ง Gateway ได้อย่างไร)

# 1) การค้นพบผ่าน Bonjour / DNS-SD

Bonjour แบบมัลติคาสต์เป็นแบบพยายามให้ดีที่สุดและไม่ข้ามเครือข่าย OpenClaw ยังสามารถเรียกดู สัญญาณประกาศ Gateway เดียวกันผ่านโดเมน DNS-SD แบบพื้นที่กว้างที่กำหนดค่าไว้ได้ ดังนั้นการค้นพบจึงครอบคลุมได้:

• local. บน LAN เดียวกัน
• โดเมน DNS-SD แบบยูนิคาสต์ที่กำหนดค่าไว้สำหรับการค้นพบข้ามเครือข่าย

ทิศทางเป้าหมาย:

• Gateway ประกาศปลายทาง WS ของตนผ่าน Bonjour เมื่อ Plugin bonjour ที่มาพร้อมกันถูกเปิดใช้งาน Plugin จะเริ่มอัตโนมัติบนโฮสต์ macOS และ ต้องเลือกเปิดใช้เองในที่อื่น
• ไคลเอนต์เรียกดูและแสดงรายการ "เลือก Gateway" จากนั้นจัดเก็บปลายทางที่เลือกไว้

รายละเอียดการแก้ปัญหาและสัญญาณประกาศ: Bonjour

# รายละเอียดสัญญาณประกาศบริการ

• ประเภทบริการ:
  • _openclaw-gw._tcp (สัญญาณประกาศการขนส่ง Gateway)
• คีย์ TXT (ไม่ใช่ความลับ):
  • role=gateway
  • transport=gateway
  • displayName=<friendly name> (ชื่อที่แสดงซึ่งโอเปอเรเตอร์กำหนดค่า)
  • lanHost=<hostname>.local
  • gatewayPort=18789 (Gateway WS + HTTP)
  • gatewayTls=1 (เฉพาะเมื่อเปิดใช้งาน TLS)
  • gatewayTlsSha256=<sha256> (เฉพาะเมื่อเปิดใช้งาน TLS และมีลายนิ้วมือ)
  • canvasPort=<port> (พอร์ตโฮสต์ canvas; ปัจจุบันเหมือนกับ gatewayPort เมื่อเปิดใช้งานโฮสต์ canvas)
  • tailnetDns=<magicdns> (คำใบ้ทางเลือก; ตรวจพบอัตโนมัติเมื่อมี Tailscale)
  • sshPort=<port> (เฉพาะโหมด mDNS เต็มรูปแบบ; DNS-SD แบบพื้นที่กว้างอาจละไว้ ซึ่งในกรณีนั้นค่าเริ่มต้น SSH จะยังคงเป็น 22)
  • cliPath=<path> (เฉพาะโหมด mDNS เต็มรูปแบบ; DNS-SD แบบพื้นที่กว้างยังคงเขียนค่านี้เป็นคำใบ้การติดตั้งระยะไกล)

หมายเหตุด้านความปลอดภัย:

• ระเบียน TXT ของ Bonjour/mDNS ไม่ได้รับการยืนยันตัวตน ไคลเอนต์ต้องถือว่าค่า TXT เป็นเพียงคำใบ้ด้าน UX เท่านั้น
• การกำหนดเส้นทาง (โฮสต์/พอร์ต) ควรให้ความสำคัญกับ ปลายทางบริการที่ resolve แล้ว (SRV + A/AAAA) มากกว่า lanHost, tailnetDns หรือ gatewayPort ที่ได้จาก TXT
• การปักหมุด TLS ต้องไม่ยอมให้ gatewayTlsSha256 ที่ประกาศมาแทนที่พินที่เคยจัดเก็บไว้ก่อนหน้า
• Node บน iOS/Android ควรกำหนดให้มีการยืนยัน "เชื่อถือลายนิ้วมือนี้" อย่างชัดเจนก่อนจัดเก็บพินครั้งแรก (การตรวจสอบนอกแบนด์) เมื่อเส้นทางที่เลือกเป็นแบบปลอดภัย/อิง TLS

เปิดใช้งาน/ปิดใช้งาน/เขียนทับ:

• openclaw plugins enable bonjour เปิดใช้งานการประกาศแบบมัลติคาสต์บน LAN
• OPENCLAW_DISABLE_BONJOUR=1 ปิดใช้งานการประกาศ
• เมื่อเปิดใช้งาน Plugin Bonjour และไม่ได้ตั้งค่า OPENCLAW_DISABLE_BONJOUR Bonjour จะประกาศบนโฮสต์ปกติและปิดใช้งานอัตโนมัติภายในคอนเทนเนอร์ที่ตรวจพบ การเริ่มต้น Gateway บน macOS ที่มีการกำหนดค่าว่างจะเปิดใช้งาน Plugin โดยอัตโนมัติ; การปรับใช้บน Linux, Windows และคอนเทนเนอร์ต้องเปิดใช้งานอย่างชัดเจน ใช้ 0 เฉพาะบนโฮสต์, macvlan หรือเครือข่ายอื่นที่รองรับ mDNS; ใช้ 1 เพื่อ บังคับปิดใช้งาน
• gateway.bind ใน ~/.openclaw/openclaw.json ควบคุมโหมดการผูกของ Gateway
• OPENCLAW_SSH_PORT เขียนทับพอร์ต SSH ที่ประกาศเมื่อมีการปล่อย sshPort
• OPENCLAW_TAILNET_DNS เผยแพร่คำใบ้ tailnetDns (MagicDNS)
• OPENCLAW_CLI_PATH เขียนทับเส้นทาง CLI ที่ประกาศ

# 2) Tailnet (ข้ามเครือข่าย)

สำหรับการตั้งค่าแบบ London/Vienna นั้น Bonjour จะไม่ช่วย เป้าหมายแบบ "ตรง" ที่แนะนำคือ:

• ชื่อ Tailscale MagicDNS (แนะนำ) หรือ IP ของ tailnet ที่เสถียร

หาก Gateway ตรวจพบได้ว่ากำลังทำงานภายใต้ Tailscale ก็จะเผยแพร่ tailnetDns เป็นคำใบ้ทางเลือกสำหรับไคลเอนต์ (รวมถึงสัญญาณประกาศแบบพื้นที่กว้าง)

ตอนนี้แอป macOS ให้ความสำคัญกับชื่อ MagicDNS มากกว่า IP ดิบของ Tailscale สำหรับการค้นพบ Gateway ซึ่งช่วยเพิ่มความน่าเชื่อถือเมื่อ IP ของ tailnet เปลี่ยน (เช่น หลังจาก Node รีสตาร์ตหรือมีการกำหนด CGNAT ใหม่) เพราะชื่อ MagicDNS จะ resolve ไปยัง IP ปัจจุบันโดยอัตโนมัติ

สำหรับการจับคู่ Node บนมือถือ คำใบ้การค้นพบไม่ได้ผ่อนคลายความปลอดภัยของการขนส่งบนเส้นทาง tailnet/สาธารณะ:

• iOS/Android ยังต้องใช้เส้นทางเชื่อมต่อ tailnet/สาธารณะครั้งแรกที่ปลอดภัย (wss:// หรือ Tailscale Serve/Funnel)
• IP ดิบของ tailnet ที่ค้นพบเป็นคำใบ้สำหรับการกำหนดเส้นทาง ไม่ใช่สิทธิ์ในการใช้ ws:// ระยะไกลแบบข้อความธรรมดา
• ยังรองรับการเชื่อมต่อตรง ws:// บน LAN ส่วนตัว
• หากคุณต้องการเส้นทาง Tailscale ที่ง่ายที่สุดสำหรับ Node บนมือถือ ให้ใช้ Tailscale Serve เพื่อให้ทั้งการค้นพบและโค้ดตั้งค่า resolve ไปยังปลายทาง MagicDNS ที่ปลอดภัยเดียวกัน

# 3) เป้าหมายแบบแมนนวล / SSH

เมื่อไม่มีเส้นทางตรง (หรือปิดใช้งานแบบตรงไว้) ไคลเอนต์ยังสามารถเชื่อมต่อผ่าน SSH ได้เสมอโดยส่งต่อพอร์ต Gateway บน loopback

ดู การเข้าถึงระยะไกล

# การเลือกการขนส่ง (นโยบายไคลเอนต์)

พฤติกรรมไคลเอนต์ที่แนะนำ:

1. หากมีการกำหนดค่าปลายทางแบบตรงที่จับคู่ไว้และเข้าถึงได้ ให้ใช้ปลายทางนั้น
2. มิฉะนั้น หากการค้นพบพบ Gateway บน local. หรือโดเมนพื้นที่กว้างที่กำหนดค่าไว้ ให้เสนอทางเลือก "ใช้ Gateway นี้" แบบแตะครั้งเดียวและบันทึกเป็นปลายทางแบบตรง
3. มิฉะนั้น หากมีการกำหนดค่า DNS/IP ของ tailnet ให้ลองแบบตรง สำหรับ Node บนมือถือบนเส้นทาง tailnet/สาธารณะ แบบตรงหมายถึงปลายทางที่ปลอดภัย ไม่ใช่ ws:// ระยะไกลแบบข้อความธรรมดา
4. มิฉะนั้น ให้ถอยกลับไปใช้ SSH

# การจับคู่ + การยืนยันตัวตน (การขนส่งแบบตรง)

Gateway เป็นแหล่งความจริงสำหรับการรับ Node/ไคลเอนต์เข้าระบบ

• คำขอจับคู่ถูกสร้าง/อนุมัติ/ปฏิเสธใน Gateway (ดู การจับคู่ Gateway)
• Gateway บังคับใช้:
  • การยืนยันตัวตน (โทเค็น / คู่คีย์)
  • ขอบเขต/ACLs (Gateway ไม่ใช่พร็อกซีดิบสำหรับทุกเมธอด)
  • การจำกัดอัตรา

# ความรับผิดชอบตามคอมโพเนนต์

• Gateway: ประกาศสัญญาณค้นพบ, เป็นเจ้าของการตัดสินใจจับคู่ และโฮสต์ปลายทาง WS
• แอป macOS: ช่วยคุณเลือก Gateway, แสดงพรอมป์การจับคู่ และใช้ SSH เป็นทางสำรองเท่านั้น
• Node บน iOS/Android: เรียกดู Bonjour เพื่อความสะดวกและเชื่อมต่อกับ Gateway WS ที่จับคู่ไว้

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

• การเข้าถึงระยะไกล
• Tailscale
• การค้นพบ Bonjour