Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Wide-area Bonjour (Unicast DNS-SD) ผ่าน Tailscale

หาก node และ gateway อยู่คนละเครือข่าย multicast mDNS จะไม่ข้าม ขอบเขตนั้น คุณสามารถคง UX การค้นหาเดิมไว้ได้โดยเปลี่ยนไปใช้ unicast DNS-SD (“Wide-Area Bonjour”) ผ่าน Tailscale ขั้นตอนระดับสูง:
  1. รัน DNS server บนโฮสต์ gateway (เข้าถึงได้ผ่าน Tailnet)
  2. เผยแพร่ระเบียน DNS-SD สำหรับ _openclaw-gw._tcp ภายใต้โซนเฉพาะ (ตัวอย่าง: openclaw.internal.)
  3. กำหนดค่า Tailscale split DNS เพื่อให้โดเมนที่คุณเลือก resolve ผ่าน DNS server นั้นสำหรับ client (รวมถึง iOS)
OpenClaw รองรับโดเมนค้นหาใดก็ได้; openclaw.internal. เป็นเพียงตัวอย่าง node iOS/Android จะ browse ทั้ง local. และโดเมน wide-area ที่คุณกำหนดค่าไว้

​
การกำหนดค่า Gateway (แนะนำ)

{
  gateway: { bind: "tailnet" }, // tailnet-only (recommended)
  discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing
}

​
การตั้งค่า DNS server ครั้งเดียว (โฮสต์ gateway)

openclaw dns setup --apply
คำสั่งนี้ติดตั้ง CoreDNS และกำหนดค่าให้:
  • listen บนพอร์ต 53 เฉพาะบนอินเทอร์เฟซ Tailscale ของ gateway
  • ให้บริการโดเมนที่คุณเลือก (ตัวอย่าง: openclaw.internal.) จาก ~/.openclaw/dns/<domain>.db
ตรวจสอบจากเครื่องที่เชื่อมต่อกับ tailnet: 
dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

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

ในคอนโซลผู้ดูแลระบบ Tailscale:
  • เพิ่ม nameserver ที่ชี้ไปยัง IP tailnet ของ gateway (UDP/TCP 53)
  • เพิ่ม split DNS เพื่อให้โดเมนค้นหาของคุณใช้ nameserver นั้น
เมื่อ client ยอมรับ DNS ของ tailnet แล้ว node iOS และการค้นหาของ CLI จะสามารถ browse _openclaw-gw._tcp ในโดเมนค้นหาของคุณได้โดยไม่ต้องใช้ multicast

​
ความปลอดภัยของ Gateway listener (แนะนำ)

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

​
สิ่งที่โฆษณา

มีเพียง Gateway ที่โฆษณา _openclaw-gw._tcp การโฆษณาแบบ multicast บน LAN จัดให้โดย Plugin bonjour ที่รวมมาด้วยเมื่อเปิดใช้ Plugin; ส่วนการเผยแพร่ DNS-SD แบบ wide-area ยังคงเป็นของ Gateway

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

  • _openclaw-gw._tcp - beacon สำหรับการขนส่งของ gateway (ใช้โดย node macOS/iOS/Android)

​
คีย์ TXT (hint ที่ไม่ใช่ความลับ)

Gateway โฆษณา hint ขนาดเล็กที่ไม่ใช่ความลับเพื่อให้โฟลว์ UI สะดวก:
  • role=gateway
  • displayName=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port> (Gateway WS + HTTP)
  • gatewayTls=1 (เฉพาะเมื่อเปิดใช้ TLS)
  • gatewayTlsSha256=<sha256> (เฉพาะเมื่อเปิดใช้ TLS และมี fingerprint)
  • canvasPort=<port> (เฉพาะเมื่อเปิดใช้โฮสต์ canvas; ปัจจุบันเหมือนกับ gatewayPort)
  • transport=gateway
  • tailnetDns=<magicdns> (เฉพาะโหมด mDNS แบบ full, เป็น hint เสริมเมื่อมี Tailnet)
  • sshPort=<port> (เฉพาะโหมด full; ไม่รวมในโหมด minimal และ off)
  • cliPath=<path> (เฉพาะโหมด full; ไม่รวมในโหมด minimal และ off)
หมายเหตุด้านความปลอดภัย:
  • ระเบียน TXT ของ Bonjour/mDNS ไม่ได้ผ่านการตรวจสอบตัวตน client ต้องไม่ถือว่า TXT เป็นข้อมูล routing ที่เชื่อถือได้
  • client ควร route โดยใช้ service endpoint ที่ resolve แล้ว (SRV + A/AAAA) ให้ถือว่า lanHost, tailnetDns, gatewayPort และ gatewayTlsSha256 เป็นเพียง hint เท่านั้น
  • การตั้งเป้าหมาย SSH อัตโนมัติก็ควรใช้ service host ที่ resolve แล้วเช่นกัน ไม่ใช่ hint จาก TXT เท่านั้น
  • TLS pinning ต้องไม่อนุญาตให้ gatewayTlsSha256 ที่โฆษณามา override pin ที่เคยจัดเก็บไว้
  • node iOS/Android ควรถือว่าการเชื่อมต่อโดยตรงจากการค้นหาเป็น TLS-only และต้องให้ผู้ใช้ยืนยันอย่างชัดเจนก่อนเชื่อถือ fingerprint ครั้งแรก

​
การดีบักบน macOS

เครื่องมือที่มีในตัวและมีประโยชน์:
  • Browse instance: 
    dns-sd -B _openclaw-gw._tcp local.
  • Resolve instance หนึ่งรายการ (แทนที่ <instance>): 
    dns-sd -L "<instance>" _openclaw-gw._tcp local.
หาก browse ได้แต่ resolve ล้มเหลว โดยปกติคุณมักเจอนโยบาย LAN หรือ ปัญหากับ mDNS resolver

​
การดีบักใน log ของ Gateway

Gateway เขียนไฟล์ log แบบ rolling (พิมพ์ตอนเริ่มต้นเป็น 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 ...
watchdog ถือว่าสถานะ probing, announcing ที่ใช้งานอยู่ และการเปลี่ยนชื่อหลัง conflict ที่ยังใหม่ เป็นสถานะที่กำลังดำเนินการ หากบริการไม่เคยไปถึง announced ในที่สุด OpenClaw จะ สร้าง advertiser ใหม่ และหลังจากล้มเหลวซ้ำ ๆ จะปิดใช้ Bonjour สำหรับ โปรเซส Gateway นั้นแทนที่จะโฆษณาซ้ำไปเรื่อย ๆ Bonjour ใช้ hostname ของระบบสำหรับโฮสต์ .local ที่โฆษณาเมื่อเป็น DNS label ที่ถูกต้อง หาก hostname ของระบบมีช่องว่าง underscore หรืออักขระอื่น ที่ไม่ถูกต้องสำหรับ DNS-label OpenClaw จะ fallback ไปที่ openclaw.local ตั้งค่า OPENCLAW_MDNS_HOSTNAME=<name> ก่อนเริ่ม Gateway เมื่อคุณต้องการ host label แบบชัดเจน

​
การดีบักบน node iOS

node iOS ใช้ NWBrowser เพื่อค้นหา _openclaw-gw._tcp เพื่อเก็บ log:
  • Settings → Gateway → Advanced → Discovery Debug Logs
  • Settings → Gateway → Advanced → Discovery Logs → ทำซ้ำปัญหา → Copy
log จะรวมการเปลี่ยนสถานะของ browser และการเปลี่ยนแปลงของ result-set

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

Bonjour จะเริ่มอัตโนมัติสำหรับการเริ่ม Gateway แบบ empty-config บนโฮสต์ macOS เพราะ แอป local และ node iOS/Android ที่อยู่ใกล้กันมักพึ่งพาการค้นหาใน LAN เดียวกัน เปิดใช้ Bonjour อย่างชัดเจนเมื่อการค้นหาอัตโนมัติใน LAN เดียวกันมีประโยชน์บน Linux, Windows หรือโฮสต์อื่นที่ไม่ใช่ macOS: 
openclaw plugins enable bonjour
เมื่อเปิดใช้ Bonjour จะใช้ discovery.mdns.mode เพื่อตัดสินใจว่าจะเผยแพร่ metadata TXT มากเท่าใด โหมดเดียวกันนี้ควบคุม hint TXT เสริมในระเบียน DNS-SD แบบ wide-area ด้วย โหมดเริ่มต้นคือ minimal; ใช้ full เฉพาะเมื่อ client ต้องการ hint cliPath หรือ sshPort ใช้ off เพื่อระงับ multicast บน LAN โดยไม่เปลี่ยนการเปิดใช้ Plugin; wide-area DNS-SD ยังสามารถเผยแพร่ beacon ของ Gateway แบบ minimal ได้เมื่อ discovery.wideArea.enabled เป็น true

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

ปล่อยให้ Bonjour ปิดอยู่เมื่อการโฆษณาแบบ multicast บน LAN ไม่จำเป็น ใช้ไม่ได้ หรือเป็นผลเสีย กรณีที่พบบ่อยคือ server ที่ไม่ใช่ macOS, Docker bridge networking, WSL หรือนโยบายเครือข่ายที่ drop mDNS multicast ในสภาพแวดล้อมเหล่านั้น Gateway ยังเข้าถึงได้ผ่าน URL ที่เผยแพร่ไว้, SSH, Tailnet หรือ wide-area DNS-SD แต่การค้นหาอัตโนมัติบน LAN ไม่น่าเชื่อถือ ควรใช้ environment override ที่มีอยู่เมื่อปัญหามีขอบเขตตามการปรับใช้: 
OPENCLAW_DISABLE_BONJOUR=1
การตั้งค่านี้ปิดการโฆษณาแบบ multicast บน LAN โดยไม่เปลี่ยนการกำหนดค่า Plugin ปลอดภัยสำหรับ Docker image, service file, launch script และการดีบักเฉพาะครั้ง เพราะการตั้งค่านี้หายไปเมื่อ environment หายไป ใช้การกำหนดค่า Plugin เมื่อคุณตั้งใจปิด Plugin การค้นหา LAN ที่รวมมาด้วย สำหรับ config ของ OpenClaw นั้น: 
openclaw plugins disable bonjour

​
ข้อควรระวังของ Docker

Plugin Bonjour ที่รวมมาด้วยจะปิดการโฆษณาแบบ multicast บน LAN อัตโนมัติในคอนเทนเนอร์ ที่ตรวจพบเมื่อไม่ได้ตั้งค่า OPENCLAW_DISABLE_BONJOUR เครือข่าย Docker bridge โดยปกติจะไม่ forward mDNS multicast (224.0.0.251:5353) ระหว่างคอนเทนเนอร์ กับ LAN ดังนั้นการโฆษณาจากคอนเทนเนอร์จึงแทบไม่ทำให้การค้นหาใช้งานได้ ข้อควรระวังสำคัญ:
  • Bonjour เริ่มอัตโนมัติบนโฮสต์ macOS และต้องเลือกเปิดใช้เองที่อื่น การปล่อยให้ ปิดอยู่ไม่ได้หยุด Gateway; เพียงแค่ข้ามการโฆษณาแบบ multicast บน LAN
  • การปิดใช้ Bonjour ไม่เปลี่ยน gateway.bind; Docker ยังใช้ค่าเริ่มต้นเป็น OPENCLAW_GATEWAY_BIND=lan เพื่อให้พอร์ตโฮสต์ที่เผยแพร่ทำงานได้
  • การปิดใช้ Bonjour ไม่ได้ปิด wide-area DNS-SD ใช้การค้นหาแบบ wide-area หรือ Tailnet เมื่อ Gateway และ node ไม่ได้อยู่บน LAN เดียวกัน
  • การใช้ OPENCLAW_CONFIG_DIR เดียวกันนอก Docker ซ้ำจะไม่คงนโยบาย auto-disable ของคอนเทนเนอร์ไว้
  • ตั้งค่า OPENCLAW_DISABLE_BONJOUR=0 เฉพาะสำหรับ host networking, macvlan หรือเครือข่ายอื่น ที่ทราบว่า mDNS multicast ผ่านได้; ตั้งเป็น 1 เพื่อบังคับปิด

​
การแก้ปัญหาเมื่อ Bonjour ถูกปิดใช้

หาก node ไม่ค้นพบ Gateway อัตโนมัติอีกหลังการตั้งค่า Docker:
  1. ยืนยันว่า Gateway กำลังรันในโหมด auto, forced-on หรือ forced-off: 
    docker compose config | grep OPENCLAW_DISABLE_BONJOUR
  2. ยืนยันว่า Gateway เองเข้าถึงได้ผ่านพอร์ตที่เผยแพร่: 
    curl -fsS http://127.0.0.1:18789/healthz
  3. ใช้ target โดยตรงเมื่อ Bonjour ถูกปิดใช้:
    • Control UI หรือเครื่องมือ local: http://127.0.0.1:18789
    • client บน LAN: http://<gateway-host>:18789
    • client ข้ามเครือข่าย: Tailnet MagicDNS, Tailnet IP, SSH tunnel หรือ wide-area DNS-SD
  4. หากคุณตั้งใจเปิดใช้ Plugin Bonjour ใน Docker และบังคับโฆษณา ด้วย OPENCLAW_DISABLE_BONJOUR=0 ให้ทดสอบ multicast จากโฮสต์: 
    dns-sd -B _openclaw-gw._tcp local.
    หาก browse ได้ผลว่าง หรือ log ของ Gateway แสดงการยกเลิกจาก ciao watchdog ซ้ำ ๆ ให้คืนค่า OPENCLAW_DISABLE_BONJOUR=1 และใช้ route โดยตรงหรือ Tailnet

​
โหมดความล้มเหลวที่พบบ่อย

  • Bonjour ไม่ข้ามเครือข่าย: ใช้ Tailnet หรือ SSH
  • Multicast ถูกบล็อก: เครือข่าย Wi-Fi บางแห่งปิดใช้ mDNS
  • Advertiser ค้างอยู่ใน probing/announcing: โฮสต์ที่ multicast ถูกบล็อก, bridge ของคอนเทนเนอร์, WSL หรือการเปลี่ยนแปลงของอินเทอร์เฟซอาจทำให้ ciao advertiser อยู่ใน สถานะที่ยังไม่ announced OpenClaw จะลองซ้ำไม่กี่ครั้งแล้วปิดใช้ Bonjour สำหรับโปรเซส Gateway ปัจจุบันแทนที่จะรีสตาร์ท advertiser ไปเรื่อย ๆ
  • Docker bridge networking: Bonjour ปิดอัตโนมัติในคอนเทนเนอร์ที่ตรวจพบ ตั้งค่า OPENCLAW_DISABLE_BONJOUR=0 เฉพาะสำหรับ host, macvlan หรือเครือข่ายอื่น ที่รองรับ mDNS
  • Sleep / การเปลี่ยนแปลงของอินเทอร์เฟซ: macOS อาจ drop ผลลัพธ์ mDNS ชั่วคราว; ลองใหม่
  • Browse ได้แต่ resolve ล้มเหลว: ใช้ชื่อเครื่องให้ง่าย (หลีกเลี่ยง emoji หรือ เครื่องหมายวรรคตอน) แล้วรีสตาร์ท Gateway ชื่อ service instance มาจาก host name ดังนั้นชื่อที่ซับซ้อนเกินไปอาจทำให้ resolver บางตัวสับสนได้

​
ชื่อ instance ที่ escape แล้ว (\032)

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

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

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

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