การค้นหาและการขนส่ง

OpenClaw มีปัญหาด้านการค้นหาสองแบบที่เกี่ยวข้องกันแต่แตกต่างกัน:

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

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

คำศัพท์

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

รายละเอียดโปรโตคอล: โปรโตคอล Gateway, โปรโตคอลบริดจ์ (แบบเดิม)

เหตุผลที่มีทั้งการเชื่อมต่อโดยตรงและ SSH

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

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

1) Bonjour / DNS-SD

Bonjour แบบมัลติคาสต์ทำงานตามความสามารถและไม่สามารถข้ามเครือข่ายได้ OpenClaw ยัง รองรับการเรียกดูบีคอนของ Gateway เดียวกันผ่านโดเมน DNS-SD แบบพื้นที่กว้าง ที่กำหนดค่าไว้ ทำให้การค้นหาครอบคลุมทั้ง local. บน LAN เดียวกันและโดเมน DNS-SD แบบยูนิคาสต์ที่กำหนดค่าไว้สำหรับการค้นหาข้ามเครือข่าย

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

รายละเอียดการแก้ไขปัญหาและบีคอน: Bonjour

รายละเอียดบีคอนบริการ

• ประเภทบริการ: _openclaw-gw._tcp (บีคอนการขนส่งของ Gateway)

• คีย์ TXT (ไม่ใช่ข้อมูลลับ):

  คีย์	หมายเหตุ
  role=gateway	มีอยู่เสมอ
  transport=gateway	มีอยู่เสมอ
  displayName=<name>	ชื่อที่แสดงซึ่งผู้ดูแลระบบเป็นผู้กำหนด
  lanHost=<hostname>.local	มีเฉพาะในตัวประกาศ mDNS บน LAN เท่านั้น DNS-SD แบบพื้นที่กว้างจะไม่เขียนค่านี้
  gatewayPort=18789	พอร์ต Gateway WS + HTTP
  gatewayTls=1	มีเฉพาะเมื่อเปิดใช้งาน TLS
  gatewayTlsSha256=<sha256>	มีเฉพาะเมื่อเปิดใช้งาน TLS และมีลายนิ้วมือพร้อมใช้งาน
  tailnetDns=<magicdns>	คำแนะนำเสริม ตรวจพบโดยอัตโนมัติเมื่อ Tailscale พร้อมใช้งาน
  sshPort=<port>	มีเฉพาะเมื่อ discovery.mdns.mode="full" และจะถูกละไว้ (SSH ใช้ค่าเริ่มต้น 22) ในโหมดเริ่มต้น "minimal" ทั้งในตัวประกาศบน LAN และ DNS-SD แบบพื้นที่กว้าง
  cliPath=<path>	ใช้เงื่อนไข discovery.mdns.mode="full" เดียวกับ sshPort เป็นคำแนะนำตำแหน่ง CLI ที่ติดตั้งบนเครื่องระยะไกล

  คีย์ TXT canvasPort ถูกกำหนดไว้ในสัญญาการค้นหาของ Plugin สำหรับ พอร์ตโฮสต์แคนวาสในอนาคต แต่ขณะนี้ยังไม่มีเส้นทางโค้ดใดกำหนดค่าให้ จึง ยังไม่มีการปล่อยคีย์นี้ในปัจจุบัน

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

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

การเปิดใช้งาน ปิดใช้งาน และแทนที่ค่า:

• openclaw plugins enable bonjour เปิดใช้งานการประกาศแบบมัลติคาสต์บน LAN
• discovery.mdns.mode ใน openclaw.json ควบคุมการกระจายสัญญาณ mDNS: "minimal" (ค่าเริ่มต้น), "full" (เพิ่ม cliPath/sshPort ทั้งในบีคอนบน LAN และโซน DNS-SD แบบพื้นที่กว้างทั้งหมด) หรือ "off" (ปิดใช้งาน mDNS)
• OPENCLAW_DISABLE_BONJOUR=1 บังคับปิดการประกาศ ส่วน discovery.mdns.mode="off" จะปิดใช้งานแยกต่างหาก OPENCLAW_DISABLE_BONJOUR=0 เป็นการเลือกเปิดใช้งานอย่างชัดเจน ซึ่งแทนที่การปิดอัตโนมัติของ Plugin ภายในคอนเทนเนอร์ที่ตรวจพบ (Docker, containerd, Kubernetes, LXC) แต่จะไม่แทนที่ discovery.mdns.mode="off" Plugin bonjour ที่มาพร้อมระบบจะเริ่มทำงานโดยอัตโนมัติบน โฮสต์ macOS (enabledByDefaultOnPlatforms: ["darwin"]) และปิดใช้งานโดยอัตโนมัติ ภายในคอนเทนเนอร์ที่ตรวจพบ ส่วน Linux, Windows และการปรับใช้แบบคอนเทนเนอร์อื่น ๆ ต้องเปิดใช้งานอย่างชัดเจนด้วย plugins enable bonjour
• gateway.bind ใน ~/.openclaw/openclaw.json ควบคุมโหมดการเชื่อมโยงของ Gateway
• OPENCLAW_SSH_PORT แทนที่พอร์ต SSH ที่ประกาศ (มีผลเฉพาะ เมื่อ discovery.mdns.mode="full")
• OPENCLAW_TAILNET_DNS เผยแพร่คำแนะนำ tailnetDns (MagicDNS)
• OPENCLAW_CLI_PATH แทนที่ตำแหน่ง CLI ที่ประกาศ

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

สำหรับ Gateway ที่อยู่บนเครือข่ายทางกายภาพต่างกัน Bonjour จะไม่ช่วย เป้าหมายการเชื่อมต่อโดยตรง ที่แนะนำคือชื่อ Tailscale MagicDNS (ควรเลือกเป็นอันดับแรก) หรือ IP ของ tailnet ที่คงที่

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

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

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

3) เป้าหมายแบบกำหนดเอง / SSH

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

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

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

การจับคู่และการยืนยันตัวตน (การขนส่งโดยตรง)

Gateway เป็นแหล่งข้อมูลหลักที่เชื่อถือได้สำหรับการอนุญาต Node/ไคลเอ็นต์:

• คำขอจับคู่จะถูกสร้าง/อนุมัติ/ปฏิเสธใน Gateway (ดู การจับคู่ Gateway)
• Gateway บังคับใช้การยืนยันตัวตน (โทเค็น/คู่กุญแจ), ขอบเขต/ACL (ไม่ใช่พร็อกซีดิบ ที่เข้าถึงได้ทุกเมธอด) และการจำกัดอัตรา

ความรับผิดชอบของแต่ละองค์ประกอบ

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

เนื้อหาที่เกี่ยวข้อง

• การเข้าถึงระยะไกล
• Tailscale
• การค้นหาด้วย Bonjour