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. กำหนดค่า 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)
  • เพิ่ม 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> เฉพาะเมื่อเปิดใช้โฮสต์แคนวาส ปัจจุบันเป็นค่าเดียวกับ gatewayPort
tailnetDns=<magicdns> เฉพาะโหมด mDNS แบบ full เป็นข้อมูลบอกใบ้เสริมเมื่อ Tailnet พร้อมใช้งาน
sshPort=<port> เฉพาะโหมด full ไม่รวมอยู่ในโหมด minimal และ off
cliPath=<path> เฉพาะโหมด full ไม่รวมอยู่ในโหมด minimal และ off

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

  • ระเบียน 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 cancellation ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...
  • bonjour: disabling advertiser after ... failed restarts ...

ตัวเฝ้าระวังจะถือว่าสถานะ probing, announcing ที่กำลังทำงาน และการเปลี่ยนชื่อเนื่องจากข้อขัดแย้งที่เพิ่งเกิดขึ้น เป็นสถานะที่ยังดำเนินการอยู่ หากบริการไม่เคยเข้าสู่สถานะ announced OpenClaw จะสร้างตัวประกาศขึ้นใหม่ และหลังจากล้มเหลวซ้ำหลายครั้ง จะปิดใช้ Bonjour สำหรับกระบวนการ Gateway นั้นแทนที่จะประกาศใหม่ไปตลอด

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 แบบเครือข่ายบริเวณกว้างยังคงเผยแพร่บีคอนแบบ minimal ได้เมื่อ 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 หรือการเปลี่ยนแปลงอินเทอร์เฟซบ่อยครั้ง อาจทำให้ตัวประกาศ ciao อยู่ในสถานะที่ไม่ได้ประกาศ OpenClaw จะลองใหม่สองสามครั้ง จากนั้นปิดใช้งาน Bonjour สำหรับโปรเซส Gateway ปัจจุบัน แทนที่จะเริ่มตัวประกาศใหม่ไปเรื่อย ๆ
  • เครือข่ายบริดจ์ของ Docker: Bonjour จะปิดใช้งานโดยอัตโนมัติเมื่อตรวจพบคอนเทนเนอร์ ตั้งค่า OPENCLAW_DISABLE_BONJOUR=0 เฉพาะสำหรับเครือข่ายแบบโฮสต์ macvlan หรือเครือข่ายอื่นที่รองรับ mDNS
  • การพักเครื่อง/การเปลี่ยนแปลงอินเทอร์เฟซบ่อยครั้ง: macOS อาจไม่แสดงผลลัพธ์ mDNS ชั่วคราว ให้ลองใหม่
  • เรียกดูได้แต่แก้ชื่อไม่ได้: ใช้ชื่อเครื่องที่เรียบง่าย (หลีกเลี่ยงอีโมจิหรือเครื่องหมายวรรคตอน) แล้วเริ่ม Gateway ใหม่ ชื่ออินสแตนซ์บริการมาจากชื่อโฮสต์ ดังนั้นชื่อที่ซับซ้อนเกินไปอาจทำให้ตัวแก้ชื่อบางตัวทำงานสับสน

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

Bonjour/DNS-SD มักหลีกไบต์ในชื่ออินสแตนซ์บริการเป็นลำดับเลขฐานสิบ \DDD (ช่องว่างจะกลายเป็น \032) ซึ่งเป็นพฤติกรรมปกติในระดับโปรโตคอล ส่วนติดต่อผู้ใช้ควรถอดรหัสเพื่อแสดงผล (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 (โหมด full)
OPENCLAW_TAILNET_DNS เผยแพร่คำแนะนำ MagicDNS ใน TXT เมื่อเปิดใช้โหมด full ของ mDNS
OPENCLAW_CLI_PATH แทนที่พาธ CLI ที่ประกาศ (โหมด full)

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

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

Was this useful?
On this page

On this page