Khám phá Bonjour

OpenClaw có thể sử dụng Bonjour (mDNS/DNS-SD) để khám phá một Gateway đang hoạt động (điểm cuối WebSocket). Việc duyệt multicast local. là một tiện ích chỉ dành cho LAN: plugin bonjour đi kèm chịu trách nhiệm quảng bá trên LAN, tự động khởi động trên các máy chủ macOS và yêu cầu chủ động bật trên Linux, Windows cũng như các bản triển khai Gateway trong container. Cùng một beacon cũng có thể được phát hành qua miền DNS-SD diện rộng đã cấu hình để khám phá xuyên mạng. Khám phá hoạt động theo cơ chế nỗ lực tối đa và không thay thế kết nối dựa trên SSH hoặc Tailnet.

​

Bonjour diện rộng (DNS-SD Unicast) qua Tailscale

Nếu Node và Gateway nằm trên các mạng khác nhau, mDNS multicast không thể vượt qua ranh giới mạng. Duy trì cùng trải nghiệm khám phá bằng cách chuyển sang DNS-SD unicast (“Bonjour diện rộng”) qua Tailscale:

1. Chạy máy chủ DNS trên máy chủ Gateway, có thể truy cập qua Tailnet.
2. Phát hành các bản ghi DNS-SD cho _openclaw-gw._tcp trong một vùng chuyên dụng (ví dụ: openclaw.internal.).
3. Cấu hình split DNS của Tailscale để miền bạn chọn được phân giải qua máy chủ DNS đó cho các máy khách, bao gồm iOS.

openclaw.internal. ở trên chỉ là ví dụ — OpenClaw hỗ trợ bất kỳ miền khám phá nào. Các Node iOS/Android duyệt cả local. và miền diện rộng đã cấu hình của bạn.

​

Cấu hình Gateway

{
  gateway: { bind: "tailnet" }, // chỉ dành cho tailnet (khuyến nghị)
  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },
}

discovery.wideArea.domain cũng chấp nhận biến môi trường OPENCLAW_WIDE_AREA_DOMAIN làm phương án dự phòng khi chưa được đặt.

​

Thiết lập máy chủ DNS một lần (máy chủ Gateway, chỉ macOS)

openclaw dns setup --apply

Lệnh này chỉ dành cho macOS và yêu cầu Homebrew cùng kết nối Tailscale đang hoạt động. Lệnh cài đặt CoreDNS (brew install coredns) và cấu hình để:

• chỉ lắng nghe trên cổng 53 tại các giao diện Tailscale của Gateway
• phục vụ miền bạn chọn (ví dụ: openclaw.internal.) từ ~/.openclaw/dns/<domain>.db

Trước tiên, chạy không có --apply để xem trước kế hoạch (miền, đường dẫn tệp vùng, IP Tailnet đã phát hiện, cấu hình được khuyến nghị) mà không cài đặt bất kỳ thứ gì.

Xác thực 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 DNS của Tailscale

Trong bảng điều khiển quản trị Tailscale:

• Thêm một máy chủ tên trỏ đến IP Tailnet của Gateway (UDP/TCP 53).
• Thêm split DNS để miền khám phá của bạn sử dụng máy chủ tên đó.

Sau khi các máy khách chấp nhận DNS Tailnet, các Node iOS và cơ chế khám phá của CLI có thể duyệt _openclaw-gw._tcp trong miền khám phá của bạn mà không cần multicast.

​

Bảo mật trình lắng nghe Gateway

Cổng WS của Gateway (mặc định 18789) mặc định liên kết với loopback. Để truy cập qua LAN/Tailnet, hãy liên kết rõ ràng và giữ xác thực ở trạng thái bật. Với thiết lập chỉ dành cho Tailnet, đặt gateway.bind: "tailnet" trong ~/.openclaw/openclaw.json và khởi động lại Gateway (hoặc ứng dụng thanh menu macOS).

​

Thành phần quảng bá

Chỉ Gateway quảng bá _openclaw-gw._tcp. Quảng bá multicast trên LAN đến từ plugin bonjour đi kèm khi được bật; việc phát hành DNS-SD diện rộng vẫn do Gateway sở hữu.

​

Loại dịch vụ

• _openclaw-gw._tcp - beacon truyền tải Gateway, được các Node macOS/iOS/Android sử dụng.

​

Khóa TXT (gợi ý không bí mật)

Khóa	Khi xuất hiện
role=gateway	Luôn luôn.
displayName=<friendly name>	Luôn luôn.
lanHost=<hostname>.local	Luôn luôn.
gatewayPort=<port>	Luôn luôn (WS + HTTP của Gateway).
transport=gateway	Luôn luôn.
gatewayTls=1	Chỉ khi TLS được bật.
gatewayTlsSha256=<sha256>	Chỉ khi TLS được bật và có fingerprint.
gatewayDirectReachable=1	Chỉ khi có thể truy cập trực tiếp Gateway (không chỉ qua đường dẫn relay/proxy).
canvasPort=<port>	Chỉ khi máy chủ canvas được bật; hiện giống với gatewayPort.
tailnetDns=<magicdns>	Chỉ ở chế độ mDNS đầy đủ; gợi ý tùy chọn khi có Tailnet.
sshPort=<port>	Chỉ ở chế độ đầy đủ; bị lược bỏ trong chế độ tối thiểu và tắt.
cliPath=<path>	Chỉ ở chế độ đầy đủ; bị lược bỏ trong chế độ tối thiểu và tắt.

Lưu ý bảo mật:

• Các bản ghi TXT Bonjour/mDNS không được xác thực. Máy khách không được coi TXT là thông tin định tuyến có thẩm quyền.
• Máy khách nên định tuyến bằng điểm cuối dịch vụ đã phân giải (SRV + A/AAAA). Chỉ coi lanHost, tailnetDns, gatewayPort và gatewayTlsSha256 là gợi ý.
• Tương tự, cơ chế tự động chọn đích SSH nên sử dụng máy chủ dịch vụ đã phân giải, không phải các gợi ý chỉ từ TXT.
• Ghim TLS tuyệt đối không được cho phép gatewayTlsSha256 được quảng bá ghi đè một mã ghim đã lưu trước đó.
• Các Node iOS/Android nên coi kết nối trực tiếp dựa trên khám phá là chỉ dùng TLS và yêu cầu người dùng xác nhận rõ ràng trước khi tin cậy một fingerprint lần đầu.

​

Gỡ lỗi trên macOS

Các công cụ tích hợp sẵn:

# Duyệt các phiên bản
dns-sd -B _openclaw-gw._tcp local.

# Phân giải một phiên bản (thay thế <instance>)
dns-sd -L "<instance>" _openclaw-gw._tcp local.

Nếu duyệt hoạt động nhưng phân giải thất bại, nguyên nhân thường là chính sách LAN hoặc sự cố với trình phân giải mDNS.

​

Gỡ lỗi trong nhật ký Gateway

Gateway ghi một tệp nhật ký luân phiên (được in khi khởi động dưới dạng gateway log file: ...). Tìm các dòng bonjour:, đặc biệt là:

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

OpenClaw khởi động mỗi dịch vụ Bonjour một lần và giao việc thăm dò, thử lại, giải quyết xung đột tên cũng như phát hành lại khi giao diện thay đổi cho trình phản hồi mDNS. Điều này tránh các lần phát hành chồng lấn trong quá trình mạng biến động bình thường. Các thông báo tự thăm dò nội bộ lặp lại được loại bỏ để không thể làm tràn nhật ký Gateway.

Khi nhiều Gateway OpenClaw quảng bá từ cùng một máy chủ, Bonjour có thể thêm các hậu tố như (2) hoặc (3) để giữ tên phiên bản dịch vụ là duy nhất. Các hậu tố này là kết quả giải quyết xung đột bình thường và không biểu thị việc giám sát OCM bị trùng lặp.

Bonjour sử dụng tên máy chủ hệ thống cho máy chủ .local được quảng bá khi đó là một nhãn DNS hợp lệ. Nếu tên máy chủ hệ thống chứa dấu cách, dấu gạch dưới hoặc ký tự khác không hợp lệ trong nhãn DNS, OpenClaw sẽ chuyển sang openclaw.local. Đặt OPENCLAW_MDNS_HOSTNAME=<name> trước khi khởi động Gateway nếu bạn cần một nhãn máy chủ rõ ràng.

​

Gỡ lỗi trên Node iOS

Node iOS sử dụng NWBrowser để khám phá _openclaw-gw._tcp.

Để thu thập nhật ký: Settings -> Gateway -> Advanced -> Discovery Debug Logs, sau đó Settings -> Gateway -> Advanced -> Discovery Logs -> tái hiện -> Copy. Nhật ký bao gồm các chuyển đổi trạng thái của trình duyệt và những thay đổi trong tập kết quả.

​

Khi nào nên bật Bonjour

Bonjour tự động khởi động khi Gateway có cấu hình trống trên các máy chủ macOS, vì ứng dụng cục bộ và các Node iOS/Android lân cận thường dựa vào cơ chế khám phá trên cùng LAN.

Bật rõ ràng khi tính năng tự động khám phá trên cùng LAN hữu ích trên Linux, Windows hoặc máy chủ không phải macOS khác:

openclaw plugins enable bonjour

Khi được bật, Bonjour sử dụng discovery.mdns.mode để quyết định lượng siêu dữ liệu TXT cần phát hành; cùng chế độ đó kiểm soát các gợi ý TXT tùy chọn trong bản ghi DNS-SD diện rộng. Các chế độ:

Chế độ	Hành vi
minimal (mặc định)	Chỉ các khóa TXT cốt lõi; lược bỏ sshPort, cliPath, tailnetDns.
full	Thêm sshPort, cliPath, tailnetDns — sử dụng khi máy khách cần các gợi ý đó.
off	Ngăn multicast trên LAN mà không thay đổi trạng thái bật của plugin; DNS-SD diện rộng vẫn có thể phát hành beacon tối thiểu khi discovery.wideArea.enabled là true.

​

Khi nào nên tắt Bonjour

Để Bonjour ở trạng thái tắt khi quảng bá multicast trên LAN không cần thiết, không khả dụng hoặc có hại — các trường hợp phổ biến gồm máy chủ không phải macOS, mạng cầu nối Docker, WSL hoặc chính sách mạng chặn multicast mDNS. Vẫn có thể truy cập Gateway qua URL đã phát hành, SSH, Tailnet hoặc DNS-SD diện rộng; chỉ tính năng tự động khám phá trên LAN là không đáng tin cậy.

Sử dụng ghi đè bằng biến môi trường cho các sự cố theo phạm vi triển khai (an toàn cho image Docker, tệp dịch vụ, tập lệnh khởi chạy và gỡ lỗi một lần — thiết lập này biến mất khi môi trường không còn):

OPENCLAW_DISABLE_BONJOUR=1

Sử dụng cấu hình plugin khi bạn chủ ý muốn tắt plugin khám phá LAN đi kèm cho cấu hình OpenClaw đó:

openclaw plugins disable bonjour

​

Những điểm dễ gặp sự cố với Docker

Plugin Bonjour đi kèm tự động tắt quảng bá multicast trên LAN trong các container được phát hiện khi OPENCLAW_DISABLE_BONJOUR chưa được đặt. Mạng cầu nối Docker thường không chuyển tiếp multicast mDNS (224.0.0.251:5353) giữa container và LAN, vì vậy việc quảng bá từ container hiếm khi giúp cơ chế khám phá hoạt động.

Những điểm cần lưu ý:

• Bonjour tự động khởi động trên các máy chủ macOS và yêu cầu chủ động bật ở nơi khác. Việc để Bonjour tắt không dừng Gateway — nó chỉ bỏ qua quảng bá multicast trên LAN.
• Việc tắt Bonjour không thay đổi gateway.bind; Docker vẫn mặc định sử dụng OPENCLAW_GATEWAY_BIND=lan để cổng máy chủ đã phát hành hoạt động.
• Việc tắt Bonjour không tắt DNS-SD diện rộng. Sử dụng khám phá diện rộng hoặc Tailnet khi Gateway và Node không ở trên cùng một LAN.
• Việc tái sử dụng cùng OPENCLAW_CONFIG_DIR bên ngoài Docker không duy trì chính sách tự động tắt của container.
• Chỉ đặt OPENCLAW_DISABLE_BONJOUR=0 cho mạng máy chủ, macvlan hoặc mạng khác mà multicast mDNS được xác nhận là có thể truyền qua; đặt thành 1 để buộc tắt.

​

Khắc phục sự cố khi Bonjour bị tắt

Nếu một Node không còn tự động khám phá Gateway sau khi thiết lập Docker:

1. Xác nhận Gateway đang chạy ở chế độ tự động, buộc bật hay buộc tắt:

   docker compose config | grep OPENCLAW_DISABLE_BONJOUR
   

2. Xác nhận bản thân Gateway có thể truy cập được qua cổng đã phát hành:

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

3. Sử dụng đích trực tiếp khi Bonjour bị tắt:

   • Giao diện điều khiển hoặc công cụ cục bộ: http://127.0.0.1:18789
   • Máy khách LAN: http://<gateway-host>:18789
   • Máy khách xuyên mạng: Tailnet MagicDNS, IP Tailnet, đường hầm SSH hoặc DNS-SD diện rộng

4. Nếu bạn chủ ý bật plugin Bonjour trong Docker và buộc quảng bá bằng OPENCLAW_DISABLE_BONJOUR=0, hãy kiểm tra multicast từ máy chủ:

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

   Nếu kết quả duyệt trống hoặc nhật ký Gateway hiển thị lỗi thăm dò ciao lặp lại, hãy khôi phục OPENCLAW_DISABLE_BONJOUR=1 và sử dụng tuyến trực tiếp hoặc Tailnet.

​

Các chế độ lỗi phổ biến

• Bonjour không hoạt động xuyên mạng: sử dụng Tailnet hoặc SSH.
• Multicast bị chặn: một số mạng Wi-Fi vô hiệu hóa mDNS.
• Trình quảng bá bị kẹt ở trạng thái thăm dò/thông báo: máy chủ bị chặn multicast, cầu nối container, WSL hoặc giao diện mạng thay đổi liên tục có thể khiến trình phản hồi rơi vào trạng thái chưa được thông báo. Gateway vẫn khả dụng qua các tuyến trực tiếp, SSH, Tailnet hoặc DNS-SD diện rộng; hãy vô hiệu hóa LAN Bonjour bằng discovery.mdns.mode: "off" hoặc OPENCLAW_DISABLE_BONJOUR=1 khi multicast không khả dụng.
• Mạng cầu nối Docker: Bonjour tự động vô hiệu hóa trong các container được phát hiện. Chỉ đặt OPENCLAW_DISABLE_BONJOUR=0 cho mạng host, macvlan hoặc mạng khác hỗ trợ mDNS.
• Chế độ ngủ/giao diện mạng thay đổi liên tục: macOS có thể tạm thời làm mất các kết quả mDNS; hãy thử lại.
• Duyệt được nhưng phân giải thất bại: giữ tên máy đơn giản (tránh biểu tượng cảm xúc hoặc dấu câu), sau đó khởi động lại Gateway. Tên phiên bản dịch vụ được tạo từ tên máy chủ, vì vậy tên quá phức tạp có thể khiến một số trình phân giải bị nhầm lẫn.

​

Tên phiên bản đã thoát ký tự (\032)

Bonjour/DNS-SD thường thoát các byte trong tên phiên bản dịch vụ dưới dạng chuỗi thập phân \DDD (dấu cách trở thành \032). Đây là hành vi bình thường ở cấp độ giao thức; giao diện người dùng nên giải mã để hiển thị (iOS sử dụng BonjourEscapes.decode).

​

Bật / tắt / cấu hình

Cài đặt	Tác dụng
openclaw plugins enable bonjour	Bật Plugin khám phá LAN đi kèm trên các máy chủ mà Plugin này không được bật theo mặc định.
openclaw plugins disable bonjour	Tắt quảng bá multicast LAN bằng cách vô hiệu hóa Plugin đi kèm.
OPENCLAW_DISABLE_BONJOUR=1 (hoặc true/yes/on)	Tắt quảng bá multicast LAN mà không thay đổi cấu hình Plugin.
OPENCLAW_DISABLE_BONJOUR=0 (hoặc false/no/off)	Buộc bật quảng bá multicast LAN, kể cả bên trong các container được phát hiện.
discovery.mdns.mode	off | minimal (mặc định) | full — xem các chế độ ở trên.
gateway.bind	Kiểm soát chế độ liên kết của Gateway trong ~/.openclaw/openclaw.json.
OPENCLAW_SSH_PORT	Ghi đè cổng SSH khi sshPort được quảng bá (chế độ đầy đủ).
OPENCLAW_TAILNET_DNS	Phát hành gợi ý MagicDNS trong TXT khi chế độ mDNS đầy đủ được bật.
OPENCLAW_CLI_PATH	Ghi đè đường dẫn CLI được quảng bá (chế độ đầy đủ).

Theo mặc định, các máy chủ macOS tự động khởi động Plugin khám phá LAN đi kèm. Khi Plugin Bonjour được bật và OPENCLAW_DISABLE_BONJOUR chưa được đặt, Bonjour sẽ quảng bá trên các máy chủ thông thường và tự động vô hiệu hóa bên trong các container được phát hiện (Docker, máy Fly.io và các môi trường chạy container phổ biến).

​

Tài liệu liên quan

• Chính sách khám phá và lựa chọn phương thức truyền tải: Khám phá
• Ghép nối Node + phê duyệt: Ghép nối Gateway