OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

การค้นหาด้วย Bonjour

OpenClaw สามารถใช้ Bonjour (mDNS/DNS-SD) เพื่อค้นหา Gateway ที่ทำงานอยู่ (ปลายทาง WebSocket) การเรียกดูมัลติแคสต์ local. เป็น ความสะดวกที่ใช้ได้เฉพาะใน LAN: Plugin bonjour ที่มาพร้อมระบบเป็นเจ้าของการประกาศบน LAN โดยเริ่มทำงานอัตโนมัติบนโฮสต์ macOS และต้องเลือกเปิดใช้บน Linux, Windows และการปรับใช้ Gateway ในคอนเทนเนอร์ บีคอนเดียวกันยังสามารถเผยแพร่ผ่านโดเมน DNS-SD แบบเครือข่ายบริเวณกว้างที่กำหนดค่าไว้ เพื่อการค้นหาข้ามเครือข่าย การค้นหาเป็นแบบพยายามให้ดีที่สุดและ ไม่ ใช้แทนการเชื่อมต่อผ่าน SSH หรือ Tailnet

Bonjour แบบเครือข่ายบริเวณกว้าง (Unicast DNS-SD) ผ่าน Tailscale

หาก Node และ Gateway อยู่คนละเครือข่าย mDNS แบบมัลติแคสต์จะข้ามขอบเขตไม่ได้ รักษาประสบการณ์การค้นหาแบบเดิมไว้โดยเปลี่ยนไปใช้ DNS-SD แบบยูนิแคสต์ ("Bonjour แบบเครือข่ายบริเวณกว้าง") ผ่าน Tailscale:

  1. เรียกใช้เซิร์ฟเวอร์ DNS บนโฮสต์ Gateway ซึ่งเข้าถึงได้ผ่าน Tailnet
  2. เผยแพร่ระเบียน DNS-SD สำหรับ _openclaw-gw._tcp ภายใต้โซนเฉพาะ (ตัวอย่าง: openclaw.internal.)
  3. กำหนดค่า split DNS ของ Tailscale เพื่อให้โดเมนที่เลือกถูกแปลงชื่อผ่านเซิร์ฟเวอร์ DNS นั้นสำหรับไคลเอนต์ รวมถึง iOS

openclaw.internal. ด้านบนเป็นเพียงตัวอย่าง — OpenClaw รองรับโดเมนการค้นหาใดก็ได้ Node iOS/Android จะเรียกดูทั้ง local. และโดเมนแบบเครือข่ายบริเวณกว้างที่กำหนดค่าไว้

การกำหนดค่า Gateway

json5
{  gateway: { bind: "tailnet" }, // เฉพาะ Tailnet (แนะนำ)  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },}

discovery.wideArea.domain ยังยอมรับตัวแปรสภาพแวดล้อม OPENCLAW_WIDE_AREA_DOMAIN เป็นค่าทดแทนเมื่อไม่ได้ตั้งค่า

การตั้งค่าเซิร์ฟเวอร์ DNS ครั้งเดียว (โฮสต์ Gateway เฉพาะ macOS)

bash
openclaw dns setup --apply

คำสั่งนี้ใช้ได้เฉพาะ macOS และต้องมี Homebrew รวมถึงการเชื่อมต่อ Tailscale ที่กำลังทำงาน คำสั่งจะติดตั้ง CoreDNS (brew install coredns) และกำหนดค่าให้:

  • รับฟังบนพอร์ต 53 เฉพาะที่อินเทอร์เฟซ Tailscale ของ Gateway
  • ให้บริการโดเมนที่เลือก (ตัวอย่าง: openclaw.internal.) จาก ~/.openclaw/dns/<domain>.db

เรียกใช้โดยไม่มี --apply ก่อนเพื่อดูตัวอย่างแผน (โดเมน พาธไฟล์โซน IP ของ Tailnet ที่ตรวจพบ และการกำหนดค่าที่แนะนำ) โดยไม่ติดตั้งสิ่งใด

ตรวจสอบจากเครื่องที่เชื่อมต่อกับ Tailnet:

bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.dig @&lt;TAILNET_IPV4&gt; -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

การตั้งค่า DNS ของ Tailscale

ในคอนโซลผู้ดูแลระบบ Tailscale:

  • เพิ่มเนมเซิร์ฟเวอร์ที่ชี้ไปยัง IP ของ Tailnet ของ Gateway (UDP/TCP 53)
  • เพิ่ม split DNS เพื่อให้โดเมนการค้นหาใช้เนมเซิร์ฟเวอร์นั้น

เมื่อไคลเอนต์ยอมรับ DNS ของ Tailnet แล้ว Node iOS และการค้นหาผ่าน CLI จะเรียกดู _openclaw-gw._tcp ในโดเมนการค้นหาได้โดยไม่ต้องใช้มัลติแคสต์

ความปลอดภัยของตัวรับฟัง Gateway

พอร์ต WS ของ Gateway (ค่าเริ่มต้น 18789) จะผูกกับลูปแบ็กโดยค่าเริ่มต้น สำหรับการเข้าถึงผ่าน LAN/Tailnet ให้กำหนดการผูกอย่างชัดเจนและเปิดใช้การยืนยันตัวตนไว้ สำหรับการตั้งค่าเฉพาะ Tailnet ให้ตั้งค่า gateway.bind: "tailnet" ใน ~/.openclaw/openclaw.json แล้วเริ่ม Gateway ใหม่ (หรือแอปแถบเมนู macOS)

สิ่งที่ประกาศ

มีเพียง Gateway เท่านั้นที่ประกาศ _openclaw-gw._tcp การประกาศมัลติแคสต์บน LAN มาจาก Plugin bonjour ที่มาพร้อมระบบเมื่อเปิดใช้ ส่วนการเผยแพร่ DNS-SD แบบเครือข่ายบริเวณกว้างยังคงเป็นของ Gateway

ประเภทบริการ

  • _openclaw-gw._tcp - บีคอนการรับส่งข้อมูลของ Gateway ซึ่ง Node macOS/iOS/Android ใช้งาน

คีย์ TXT (คำใบ้ที่ไม่เป็นความลับ)

คีย์ เมื่อมีค่า
role=gateway มีเสมอ
displayName=<friendly name> มีเสมอ
lanHost=<hostname>.local มีเสมอ
gatewayPort=<port> มีเสมอ (WS + HTTP ของ Gateway)
transport=gateway มีเสมอ
gatewayTls=1 เฉพาะเมื่อเปิดใช้ TLS
gatewayTlsSha256=<sha256> เฉพาะเมื่อเปิดใช้ TLS และมีลายนิ้วมือพร้อมใช้งาน
gatewayDirectReachable=1 เฉพาะเมื่อเข้าถึง Gateway ได้โดยตรง (ไม่ใช่เฉพาะผ่านเส้นทางรีเลย์/พร็อกซี)
canvasPort=<port> เฉพาะเมื่อเปิดใช้โฮสต์ Canvas ปัจจุบันมีค่าเดียวกับ gatewayPort
tailnetDns=<magicdns> เฉพาะโหมดเต็มของ mDNS เป็นคำใบ้เสริมเมื่อ Tailnet พร้อมใช้งาน
sshPort=<port> เฉพาะโหมดเต็ม ละเว้นในโหมดขั้นต่ำและโหมดปิด
cliPath=<path> เฉพาะโหมดเต็ม ละเว้นในโหมดขั้นต่ำและโหมดปิด

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

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

การดีบักบน macOS

เครื่องมือในตัว:

bash
# เรียกดูอินสแตนซ์dns-sd -B _openclaw-gw._tcp local. # แปลงชื่อหนึ่งอินสแตนซ์ (แทนที่ <instance>)dns-sd -L "<instance>" _openclaw-gw._tcp local.

หากเรียกดูได้แต่แปลงชื่อไม่ได้ โดยทั่วไปมักเกิดจากนโยบาย LAN หรือปัญหาตัวแปลงชื่อ mDNS

การดีบักในบันทึก Gateway

Gateway เขียนไฟล์บันทึกแบบหมุนเวียน (แสดงเมื่อเริ่มต้นเป็น gateway log file: ...) ให้มองหาบรรทัด bonjour: โดยเฉพาะ:

  • bonjour: advertise failed ...
  • bonjour: suppressing ciao netmask assertion ...
  • bonjour: ... name conflict resolved / hostname conflict resolved

OpenClaw เริ่มบริการ Bonjour แต่ละรายการหนึ่งครั้ง และปล่อยให้ตัวตอบสนอง mDNS จัดการการตรวจสอบ การลองใหม่ การแก้ไขชื่อที่ขัดแย้ง และการเผยแพร่ซ้ำเมื่ออินเทอร์เฟซเปลี่ยนแปลง วิธีนี้ช่วยหลีกเลี่ยงความพยายามเผยแพร่ที่ทับซ้อนกันระหว่างความผันผวนตามปกติของเครือข่าย ข้อความตรวจสอบตัวเองภายในที่เกิดซ้ำจะถูกระงับเพื่อไม่ให้ท่วมบันทึกของ Gateway

เมื่อ Gateway ของ OpenClaw หลายรายการประกาศจากโฮสต์เดียวกัน Bonjour อาจต่อท้ายส่วนเสริม เช่น (2) หรือ (3) เพื่อให้ชื่ออินสแตนซ์บริการไม่ซ้ำกัน ส่วนเสริมเหล่านี้เป็นการแก้ไขความขัดแย้งตามปกติ และไม่ได้บ่งชี้ว่ามีการกำกับดูแล OCM ซ้ำซ้อน

Bonjour ใช้ชื่อโฮสต์ของระบบเป็นโฮสต์ .local ที่ประกาศ หากเป็นป้ายกำกับ DNS ที่ถูกต้อง หากชื่อโฮสต์ของระบบมีช่องว่าง ขีดล่าง หรืออักขระอื่นที่ใช้ในป้ายกำกับ DNS ไม่ได้ OpenClaw จะใช้ openclaw.local แทน ตั้งค่า OPENCLAW_MDNS_HOSTNAME=<name> ก่อนเริ่ม Gateway เมื่อต้องการป้ายกำกับโฮสต์ที่ระบุชัดเจน

การดีบักบน Node iOS

Node iOS ใช้ NWBrowser เพื่อค้นหา _openclaw-gw._tcp

วิธีเก็บบันทึก: Settings -> Gateway -> Advanced -> Discovery Debug Logs จากนั้น Settings -> Gateway -> Advanced -> Discovery Logs -> ทำให้เกิดปัญหาซ้ำ -> Copy บันทึกประกอบด้วยการเปลี่ยนสถานะของเบราว์เซอร์และการเปลี่ยนแปลงชุดผลลัพธ์

เมื่อใดควรเปิดใช้ Bonjour

Bonjour เริ่มทำงานอัตโนมัติเมื่อเริ่ม Gateway ด้วยการกำหนดค่าว่างบนโฮสต์ macOS เนื่องจากแอปภายในเครื่องและ Node iOS/Android ที่อยู่ใกล้เคียงมักพึ่งพาการค้นหาภายใน LAN เดียวกัน

เปิดใช้อย่างชัดเจนเมื่อการค้นหาอัตโนมัติภายใน LAN เดียวกันมีประโยชน์บน Linux, Windows หรือโฮสต์อื่นที่ไม่ใช่ macOS:

bash
openclaw plugins enable bonjour

เมื่อเปิดใช้ Bonjour จะใช้ discovery.mdns.mode เพื่อกำหนดปริมาณเมทาดาทา TXT ที่จะเผยแพร่ และโหมดเดียวกันนี้จะควบคุมคำใบ้ TXT เสริมในระเบียน DNS-SD แบบเครือข่ายบริเวณกว้าง โหมดต่าง ๆ:

โหมด ลักษณะการทำงาน
minimal (ค่าเริ่มต้น) เฉพาะคีย์ TXT หลัก โดยละเว้น sshPort, cliPath, tailnetDns
full เพิ่ม sshPort, cliPath, tailnetDns — ใช้เมื่อไคลเอนต์ต้องการคำใบ้เหล่านั้น
off ระงับมัลติแคสต์ LAN โดยไม่เปลี่ยนสถานะการเปิดใช้ Plugin ส่วน DNS-SD แบบเครือข่ายบริเวณกว้างยังเผยแพร่บีคอนขั้นต่ำได้เมื่อ discovery.wideArea.enabled เป็นจริง

เมื่อใดควรปิดใช้ Bonjour

ปล่อยให้ Bonjour ปิดใช้อยู่เมื่อการประกาศมัลติแคสต์บน LAN ไม่จำเป็น ใช้งานไม่ได้ หรือเป็นผลเสีย — กรณีที่พบบ่อย ได้แก่ เซิร์ฟเวอร์ที่ไม่ใช่ macOS, เครือข่ายบริดจ์ของ Docker, WSL หรือนโยบายเครือข่ายที่ทิ้งมัลติแคสต์ mDNS Gateway ยังคงเข้าถึงได้ผ่าน URL ที่เผยแพร่, SSH, Tailnet หรือ DNS-SD แบบเครือข่ายบริเวณกว้าง มีเพียงการค้นหาอัตโนมัติบน LAN เท่านั้นที่ไม่น่าเชื่อถือ

ใช้การเขียนทับด้วยตัวแปรสภาพแวดล้อมสำหรับปัญหาที่จำกัดเฉพาะการปรับใช้ (ปลอดภัยสำหรับอิมเมจ Docker, ไฟล์บริการ, สคริปต์เรียกใช้ และการดีบักเฉพาะกิจ — ค่านี้จะหายไปเมื่อสภาพแวดล้อมหายไป):

bash
OPENCLAW_DISABLE_BONJOUR=1

ใช้การกำหนดค่า Plugin เมื่อตั้งใจปิด Plugin การค้นหาบน LAN ที่มาพร้อมระบบสำหรับการกำหนดค่า OpenClaw นั้น:

bash
openclaw plugins disable bonjour

ข้อควรระวังเกี่ยวกับ Docker

Plugin Bonjour ที่มาพร้อมระบบจะปิดการประกาศมัลติแคสต์บน LAN โดยอัตโนมัติในคอนเทนเนอร์ที่ตรวจพบเมื่อไม่ได้ตั้งค่า OPENCLAW_DISABLE_BONJOUR โดยปกติเครือข่ายบริดจ์ของ Docker จะไม่ส่งต่อมัลติแคสต์ mDNS (224.0.0.251:5353) ระหว่างคอนเทนเนอร์กับ LAN ดังนั้นการประกาศจากคอนเทนเนอร์จึงแทบไม่ทำให้การค้นหาทำงาน

ข้อควรระวัง:

  • Bonjour เริ่มทำงานอัตโนมัติบนโฮสต์ macOS และต้องเลือกเปิดใช้ในที่อื่น การปล่อยให้ปิดใช้อยู่ไม่ได้หยุด Gateway — เพียงข้ามการประกาศมัลติแคสต์บน LAN
  • การปิดใช้ Bonjour ไม่เปลี่ยน gateway.bind; Docker ยังคงใช้ค่าเริ่มต้นเป็น OPENCLAW_GATEWAY_BIND=lan เพื่อให้พอร์ตโฮสต์ที่เผยแพร่ทำงาน
  • การปิดใช้ Bonjour ไม่ได้ปิด DNS-SD แบบเครือข่ายบริเวณกว้าง ใช้การค้นหาแบบเครือข่ายบริเวณกว้างหรือ Tailnet เมื่อ Gateway และ Node ไม่ได้อยู่ใน LAN เดียวกัน
  • การนำ OPENCLAW_CONFIG_DIR เดิมกลับมาใช้นอก Docker จะไม่คงนโยบายปิดอัตโนมัติของคอนเทนเนอร์ไว้
  • ตั้งค่า OPENCLAW_DISABLE_BONJOUR=0 เฉพาะสำหรับเครือข่ายโฮสต์, macvlan หรือเครือข่ายอื่นที่ทราบว่ามัลติแคสต์ mDNS ผ่านได้ ตั้งค่าเป็น 1 เพื่อบังคับปิด

การแก้ไขปัญหา Bonjour ที่ถูกปิดใช้

หาก Node ไม่ค้นพบ Gateway โดยอัตโนมัติอีกต่อไปหลังตั้งค่า Docker:

  1. ยืนยันว่า Gateway กำลังทำงานในโหมดอัตโนมัติ บังคับเปิด หรือบังคับปิด:

    bash
    docker compose config | grep OPENCLAW_DISABLE_BONJOUR

  2. ยืนยันว่าเข้าถึง Gateway ได้ผ่านพอร์ตที่เผยแพร่:

    bash
    curl -fsS http://127.0.0.1:18789/healthz

  3. ใช้เป้าหมายโดยตรงเมื่อปิดใช้ Bonjour:

    • Control UI หรือเครื่องมือภายในเครื่อง: http://127.0.0.1:18789
    • ไคลเอนต์ LAN: http://<gateway-host>:18789
    • ไคลเอนต์ข้ามเครือข่าย: Tailnet MagicDNS, IP ของ Tailnet, อุโมงค์ SSH หรือ DNS-SD แบบเครือข่ายบริเวณกว้าง

  4. หากตั้งใจเปิดใช้ Plugin Bonjour ใน Docker และบังคับการประกาศด้วย OPENCLAW_DISABLE_BONJOUR=0 ให้ทดสอบมัลติแคสต์จากโฮสต์:

    bash
    dns-sd -B _openclaw-gw._tcp local.

    หากการเรียกดูว่างเปล่า หรือบันทึก Gateway แสดงความล้มเหลวในการตรวจสอบ ciao ซ้ำ ๆ ให้คืนค่า OPENCLAW_DISABLE_BONJOUR=1 และใช้เส้นทางโดยตรงหรือ Tailnet

รูปแบบความล้มเหลวที่พบบ่อย

  • Bonjour ไม่ทำงานข้ามเครือข่าย: ใช้ Tailnet หรือ SSH
  • มัลติแคสต์ถูกบล็อก: เครือข่าย Wi-Fi บางแห่งปิดใช้งาน mDNS
  • ตัวประกาศค้างอยู่ในสถานะตรวจสอบ/ประกาศ: โฮสต์ที่บล็อกมัลติแคสต์ บริดจ์ของคอนเทนเนอร์ WSL หรือการเปลี่ยนแปลงอินเทอร์เฟซบ่อยครั้ง อาจทำให้ตัวตอบสนองอยู่ในสถานะที่ยังไม่ได้ประกาศ Gateway ยังคงเข้าถึงได้ผ่านเส้นทางโดยตรง, SSH, Tailnet หรือ DNS-SD แบบเครือข่ายบริเวณกว้าง ให้ปิดใช้งาน Bonjour บน LAN ด้วย discovery.mdns.mode: "off" หรือ OPENCLAW_DISABLE_BONJOUR=1 เมื่อไม่สามารถใช้มัลติแคสต์ได้
  • เครือข่ายบริดจ์ของ Docker: Bonjour จะปิดใช้งานโดยอัตโนมัติในคอนเทนเนอร์ที่ตรวจพบ ตั้งค่า OPENCLAW_DISABLE_BONJOUR=0 เฉพาะสำหรับเครือข่ายแบบโฮสต์, macvlan หรือเครือข่ายอื่นที่รองรับ mDNS
  • การพักเครื่อง/การเปลี่ยนแปลงอินเทอร์เฟซ: macOS อาจไม่แสดงผลลัพธ์ mDNS ชั่วคราว ให้ลองอีกครั้ง
  • เรียกดูได้แต่แก้ชื่อไม่ได้: ใช้ชื่อเครื่องแบบเรียบง่าย (หลีกเลี่ยงอีโมจิหรือเครื่องหมายวรรคตอน) แล้วรีสตาร์ต Gateway ชื่ออินสแตนซ์บริการสร้างมาจากชื่อโฮสต์ ดังนั้นชื่อที่ซับซ้อนเกินไปอาจทำให้ตัวแก้ชื่อบางตัวสับสนได้

ชื่ออินสแตนซ์ที่มีการหลีกอักขระ (\032)

Bonjour/DNS-SD มักหลีกไบต์ในชื่ออินสแตนซ์บริการเป็นลำดับเลขฐานสิบ \DDD (ช่องว่างจะกลายเป็น \032) ซึ่งเป็นเรื่องปกติในระดับโปรโตคอล UI ควรถอดรหัสเพื่อแสดงผล (iOS ใช้ BonjourEscapes.decode)

การเปิดใช้งาน / การปิดใช้งาน / การกำหนดค่า

การตั้งค่า ผล
openclaw plugins enable bonjour เปิดใช้งาน Plugin การค้นหาบน LAN ที่ให้มาด้วยบนโฮสต์ซึ่งไม่ได้เปิดใช้งานเป็นค่าเริ่มต้น
openclaw plugins disable bonjour ปิดการโฆษณามัลติแคสต์บน LAN โดยปิดใช้งาน Plugin ที่ให้มาด้วย
OPENCLAW_DISABLE_BONJOUR=1 (หรือ true/yes/on) ปิดการโฆษณามัลติแคสต์บน LAN โดยไม่เปลี่ยนการกำหนดค่า Plugin
OPENCLAW_DISABLE_BONJOUR=0 (หรือ false/no/off) บังคับเปิดการโฆษณามัลติแคสต์บน LAN รวมถึงภายในคอนเทนเนอร์ที่ตรวจพบ
discovery.mdns.mode off | minimal (ค่าเริ่มต้น) | full — ดูโหมดด้านบน
gateway.bind ควบคุมโหมดการผูกของ Gateway ใน ~/.openclaw/openclaw.json
OPENCLAW_SSH_PORT เขียนทับพอร์ต SSH เมื่อมีการโฆษณา sshPort (โหมดเต็ม)
OPENCLAW_TAILNET_DNS เผยแพร่คำใบ้ MagicDNS ใน TXT เมื่อเปิดใช้งานโหมดเต็มของ mDNS
OPENCLAW_CLI_PATH เขียนทับพาธ CLI ที่โฆษณา (โหมดเต็ม)

โฮสต์ macOS จะเริ่ม Plugin การค้นหาบน LAN ที่ให้มาด้วยโดยอัตโนมัติเป็นค่าเริ่มต้น เมื่อเปิดใช้งาน Plugin Bonjour และไม่ได้ตั้งค่า OPENCLAW_DISABLE_BONJOUR Bonjour จะโฆษณาบนโฮสต์ปกติและปิดใช้งานโดยอัตโนมัติภายในคอนเทนเนอร์ที่ตรวจพบ (Docker, เครื่อง Fly.io และรันไทม์คอนเทนเนอร์ทั่วไป)

เอกสารที่เกี่ยวข้อง

Was this useful?
On this page

On this page