> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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/.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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} dns-sd -B _openclaw-gw._tcp openclaw.internal. dig @ -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=` | Luôn luôn. | | `lanHost=.local` | Luôn luôn. | | `gatewayPort=` | Luôn luôn (WS + HTTP của Gateway). | | `transport=gateway` | Luôn luôn. | | `gatewayTls=1` | Chỉ khi TLS được bật. | | `gatewayTlsSha256=` | 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=` | Chỉ khi máy chủ canvas được bật; hiện giống với `gatewayPort`. | | `tailnetDns=` | Chỉ ở chế độ mDNS đầy đủ; gợi ý tùy chọn khi có Tailnet. | | `sshPort=` | Chỉ ở chế độ đầy đủ; bị lược bỏ trong chế độ tối thiểu và tắt. | | `cliPath=` | 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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ế ) dns-sd -L "" _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=` 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 đó: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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://: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ủ: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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á](/vi/gateway/discovery) * Ghép nối Node + phê duyệt: [Ghép nối Gateway](/vi/gateway/pairing)