Bonjour / mDNS discovery

OpenClaw sử dụng Bonjour (mDNS / DNS‑SD) như một tiện ích chỉ dành cho LAN để phát hiện Gateway đang hoạt động (WebSocket endpoint). Đây là cơ chế best-effort và không thay thế kết nối qua SSH hoặc Tailnet.

Wide‑area Bonjour (Unicast DNS‑SD) qua Tailscale

Nếu node và gateway ở các mạng khác nhau, multicast mDNS sẽ không vượt qua được ranh giới mạng. Các bạn có thể giữ nguyên trải nghiệm discovery bằng cách chuyển sang unicast DNS‑SD (“Wide‑Area Bonjour”) qua Tailscale.

Các bước tổng quan:

  1. Chạy DNS server trên máy chủ gateway (có thể truy cập qua Tailnet).
  2. Publish các bản ghi DNS‑SD cho _openclaw-gw._tcp dưới một zone riêng (ví dụ: openclaw.internal.).
  3. Cấu hình Tailscale split DNS để domain các bạn chọn được phân giải qua DNS server đó cho các client (bao gồm cả iOS).

OpenClaw hỗ trợ bất kỳ discovery domain nào; openclaw.internal. chỉ là một ví dụ. Các node iOS/Android sẽ browse cả local. và wide‑area domain mà các bạn đã cấu hình.

Cấu hình Gateway (khuyên dùng)

{
  gateway: { bind: "tailnet" }, // chỉ tailnet (khuyên dùng)
  discovery: { wideArea: { enabled: true } }, // bật wide-area DNS-SD publishing
}

Thiết lập DNS server một lần (trên máy chủ gateway)

openclaw dns setup --apply

Lệnh này sẽ cài đặt CoreDNS và cấu hình để:

  • listen trên port 53 chỉ trên các interface Tailscale của gateway
  • serve domain các bạn chọn (ví dụ: openclaw.internal.) từ ~/.openclaw/dns/<domain>.db

Kiểm tra từ một máy đã kết nối tailnet:

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Cài đặt Tailscale DNS

Trong Tailscale admin console:

  • Thêm nameserver trỏ đến tailnet IP của gateway (UDP/TCP 53).
  • Thêm split DNS để discovery domain của các bạn sử dụng nameserver đó.

Khi các client chấp nhận tailnet DNS, các node iOS có thể browse _openclaw-gw._tcp trong discovery domain của các bạn mà không cần multicast.

Bảo mật Gateway listener (khuyên dùng)

Gateway WS port (mặc định 18789) bind vào loopback theo mặc định. Để truy cập qua LAN/tailnet, hãy bind rõ ràng và giữ auth được bật.

Đối với thiết lập chỉ dùng tailnet:

  • Đặt gateway.bind: "tailnet" trong ~/.openclaw/openclaw.json.
  • Khởi động lại Gateway (hoặc khởi động lại macOS menubar app).

Cái gì advertise

Chỉ có Gateway advertise _openclaw-gw._tcp.

Service types

  • _openclaw-gw._tcp — gateway transport beacon (được sử dụng bởi các node macOS/iOS/Android).

TXT keys (non‑secret hints)

Gateway advertise các gợi ý nhỏ không bí mật để làm cho UI flow thuận tiện hơn:

  • role=gateway
  • displayName=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port> (Gateway WS + HTTP)
  • gatewayTls=1 (chỉ khi TLS được bật)
  • gatewayTlsSha256=<sha256> (chỉ khi TLS được bật và fingerprint có sẵn)
  • canvasPort=<port> (chỉ khi canvas host được bật; mặc định 18793)
  • sshPort=<port> (mặc định là 22 khi không bị override)
  • transport=gateway
  • cliPath=<path> (tùy chọn; đường dẫn tuyệt đối đến entrypoint openclaw có thể chạy được)
  • tailnetDns=<magicdns> (gợi ý tùy chọn khi Tailnet có sẵn)

Debug trên macOS

Các công cụ built‑in hữu ích:

  • Browse các instance: 
    dns-sd -B _openclaw-gw._tcp local.
  • Resolve một instance (thay <instance>): 
    dns-sd -L "<instance>" _openclaw-gw._tcp local.

Nếu browsing hoạt động nhưng resolving thất bại, các bạn thường đang gặp vấn đề về LAN policy hoặc mDNS resolver.

Debug trong Gateway logs

Gateway ghi một file log rolling (được in ra khi khởi động dưới dạng gateway log file: ...). Tìm các dòng bonjour:, đặc biệt:

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

Debug trên iOS node

iOS node sử dụng NWBrowser để discover _openclaw-gw._tcp.

Để capture logs:

  • Settings → Gateway → Advanced → Discovery Debug Logs
  • Settings → Gateway → Advanced → Discovery Logs → reproduce → Copy

Log bao gồm các chuyển đổi trạng thái browser và thay đổi result‑set.

Các chế độ lỗi thường gặp

  • Bonjour không vượt qua các mạng: dùng Tailnet hoặc SSH.
  • Multicast bị chặn: một số mạng Wi‑Fi vô hiệu hóa mDNS.
  • Sleep / interface churn: macOS có thể tạm thời drop các kết quả mDNS; thử lại.
  • Browse hoạt động nhưng resolve thất bại: giữ tên máy đơn giản (tránh emoji hoặc dấu câu), sau đó khởi động lại Gateway. Tên service instance được lấy từ tên host, nên các tên quá phức tạp có thể làm một số resolver bị nhầm lẫn.

Escaped instance names (\032)

Bonjour/DNS‑SD thường escape các byte trong service instance names thành các chuỗi thập phân \DDD (ví dụ: dấu cách trở thành \032).

  • Đây là điều bình thường ở mức protocol.
  • UI nên decode để hiển thị (iOS sử dụng BonjourEscapes.decode).

Vô hiệu hóa / cấu hình

  • OPENCLAW_DISABLE_BONJOUR=1 vô hiệu hóa advertising (legacy: OPENCLAW_DISABLE_BONJOUR).
  • gateway.bind trong ~/.openclaw/openclaw.json điều khiển Gateway bind mode.
  • OPENCLAW_SSH_PORT override SSH port được advertise trong TXT (legacy: OPENCLAW_SSH_PORT).
  • OPENCLAW_TAILNET_DNS publish một MagicDNS hint trong TXT (legacy: OPENCLAW_TAILNET_DNS).
  • OPENCLAW_CLI_PATH override CLI path được advertise (legacy: OPENCLAW_CLI_PATH).

Tài liệu liên quan