การค้นหาและวิธีการเชื่อมต่อ (transports)¶

OpenClawมีปัญหาสองอย่างที่ดูคล้ายกันบนผิวเผิน:

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

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

คำศัพท์¶

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

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

• โปรโตคอล Gateway
• โปรโตคอล Bridge (legacy)

เหตุผลที่เรายังคงใช้ทั้งแบบ “direct” และ SSH¶

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

อินพุตสำหรับการค้นหา (ไคลเอนต์ทราบตำแหน่งของ gateway ได้อย่างไร)¶

1. Bonjour / mDNS (LAN only)¶

22. Bonjour เป็นแบบ best-effort และไม่ข้ามเครือข่าย Bonjourเป็นแบบbest-effortและไม่ข้ามเครือข่าย ใช้เพื่อความสะดวกในกรณี “LANเดียวกัน” เท่านั้น

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

• gateway ประกาศเอนด์พอยต์WSผ่านBonjour
• ไคลเอนต์ค้นหาและแสดงรายการ “เลือกเกตเวย์” จากนั้นบันทึกเอนด์พอยต์ที่เลือก

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

รายละเอียด Service beacon¶

• ประเภทบริการ:
• _openclaw-gw._tcp (บีคอนทรานสปอร์ตเกตเวย์)
• คีย์TXT(ไม่เป็นความลับ):
• role=gateway
• lanHost=<hostname>.local
• sshPort=22 (หรือสิ่งที่ถูกประกาศ)
• gatewayPort=18789 (Gateway WS + HTTP)
• gatewayTls=1 (เฉพาะเมื่อเปิดใช้TLS)
• gatewayTlsSha256=<sha256> (เฉพาะเมื่อเปิดใช้TLSและมีfingerprint)
• canvasPort=18793 (พอร์ตโฮสต์canvasค่าเริ่มต้น; ให้บริการ /__openclaw__/canvas/)
• cliPath=<path> (ไม่บังคับ; พาธแบบสัมบูรณ์ไปยังเอนทรีพอยต์หรือไบนารี openclaw ที่รันได้)
• tailnetDns=<magicdns> (คำใบ้ไม่บังคับ; ตรวจจับอัตโนมัติเมื่อมีTailscale)

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

• OPENCLAW_DISABLE_BONJOUR=1 ปิดการประกาศ
• gateway.bind ใน ~/.openclaw/openclaw.json ควบคุมโหมดการผูกของGateway
• OPENCLAW_SSH_PORT เขียนทับพอร์ตSSHที่ประกาศในTXT(ค่าเริ่มต้นคือ22)
• OPENCLAW_TAILNET_DNS เผยแพร่คำใบ้ tailnetDns (MagicDNS)
• OPENCLAW_CLI_PATH เขียนทับพาธCLIที่ประกาศ

2. Tailnet (cross-network)¶

23. สำหรับการตั้งค่าแบบลอนดอน/เวียนนา Bonjour จะไม่ช่วย 24. เป้าหมายแบบ “direct” ที่แนะนำคือ:

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

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

3. Manual / SSH target¶

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

ดู Remote access.

Transport selection (client policy)¶

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

1. หากมีเอนด์พอยต์โดยตรงที่จับคู่แล้วและเข้าถึงได้ ให้ใช้เอนด์พอยต์นั้น
2. มิฉะนั้น หากBonjourพบเกตเวย์บนLAN ให้เสนอทางเลือก “ใช้เกตเวย์นี้” แบบแตะครั้งเดียวและบันทึกเป็นเอนด์พอยต์โดยตรง
3. มิฉะนั้น หากมีการกำหนดDNS/IPของtailnet ให้ลองเชื่อมต่อโดยตรง
4. มิฉะนั้น ให้ถอยกลับไปใช้SSH

Pairing + auth (direct transport)¶

เกตเวย์เป็นแหล่งความจริงสำหรับการรับโหนด/ไคลเอนต์

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

Responsibilities by component¶

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