Skip to main content
OpenClaw може використовувати Bonjour (mDNS/DNS-SD) для виявлення активного Gateway (кінцевої точки WebSocket). Перегляд багатоадресного local. — це зручність лише для LAN: вбудований Plugin bonjour відповідає за оголошення в LAN, автоматично запускаючись на хостах macOS і вмикаючись за бажанням у розгортаннях Gateway на Linux, Windows і в контейнерах. Той самий маяк також може публікуватися через налаштований домен широкозонного DNS-SD для виявлення між мережами. Виявлення працює за принципом докладання максимальних зусиль і не замінює підключення через SSH або Tailnet.

​
Широкозонний Bonjour (одноадресний 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, щоб вибраний домен для клієнтів, зокрема iOS, розпізнавався через цей DNS-сервер.
Наведений вище openclaw.internal. — лише приклад: OpenClaw підтримує будь-який домен виявлення. Вузли iOS/Android переглядають як local., так і налаштований широкозонний домен.

​
Конфігурація Gateway

discovery.wideArea.domain також приймає змінну середовища OPENCLAW_WIDE_AREA_DOMAIN як резервний варіант, якщо значення не задано.

​
Одноразове налаштування DNS-сервера (хост Gateway, лише macOS)

Ця команда доступна лише в macOS і потребує Homebrew та активного підключення Tailscale. Вона встановлює CoreDNS (brew install coredns) і налаштовує його так, щоб він:
  • прослуховував порт 53 лише на інтерфейсах Tailscale хоста Gateway
  • обслуговував вибраний домен (приклад: openclaw.internal.) із ~/.openclaw/dns/<domain>.db
Спочатку запустіть без --apply, щоб переглянути план (домен, шлях до файлу зони, виявлену IP-адресу Tailnet, рекомендовану конфігурацію), нічого не встановлюючи. Перевірте з комп’ютера, підключеного до Tailnet:

​
Налаштування DNS Tailscale

У консолі адміністрування Tailscale:
  • Додайте сервер імен, що вказує на IP-адресу Tailnet хоста Gateway (UDP/TCP 53).
  • Додайте розділений DNS, щоб домен виявлення використовував цей сервер імен.
Щойно клієнти приймуть DNS Tailnet, вузли iOS і засоби виявлення CLI зможуть переглядати _openclaw-gw._tcp у домені виявлення без багатоадресного передавання.

​
Безпека прослуховувача Gateway

Порт WS Gateway (типово 18789) за замовчуванням прив’язується до loopback. Для доступу через 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, який використовують вузли macOS/iOS/Android.

​
Ключі TXT (несекретні підказки)

Примітки щодо безпеки:
  • Записи TXT Bonjour/mDNS не автентифіковані. Клієнти не повинні вважати TXT авторитетним джерелом маршрутизації.
  • Клієнти мають виконувати маршрутизацію за розпізнаною кінцевою точкою служби (SRV + A/AAAA). Вважайте lanHost, tailnetDns, gatewayPort і gatewayTlsSha256 лише підказками.
  • Автоматичний вибір цілі SSH також має використовувати розпізнаний хост служби, а не лише підказки TXT.
  • Закріплення TLS ніколи не повинно дозволяти оголошеному gatewayTlsSha256 перевизначати раніше збережлене закріплення.
  • Вузли iOS/Android мають вважати прямі підключення на основі виявлення доступними лише через TLS і вимагати явного підтвердження користувача, перш ніж довіряти відбитку вперше.

​
Налагодження в macOS

Вбудовані інструменти:
Якщо перегляд працює, але розпізнавання завершується помилкою, зазвичай причина в політиці LAN або засобі розпізнавання mDNS.

​
Налагодження в журналах Gateway

Gateway записує циклічний файл журналу (під час запуску його виведено як gateway log file: ...). Шукайте рядки bonjour:, особливо:
  • bonjour: advertise failed ...
  • bonjour: suppressing ciao netmask assertion ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
OpenClaw запускає кожну службу Bonjour один раз і передає зондування, повторні спроби, розв’язання конфліктів імен і повторну публікацію після зміни інтерфейсу засобу відповіді mDNS. Це запобігає накладанню спроб публікації під час звичайних змін стану мережі. Повторювані внутрішні повідомлення самозондування пригнічуються, щоб вони не могли переповнити журнал Gateway. Коли кілька Gateway OpenClaw оголошуються з одного хоста, Bonjour може додавати суфікси на кшталт (2) або (3), щоб імена екземплярів служб залишалися унікальними. Такі суфікси є звичайним механізмом розв’язання конфліктів і не свідчать про дублювання нагляду OCM. Bonjour використовує системне ім’я хоста для оголошуваного хоста .local, якщо воно є припустимою міткою DNS. Якщо системне ім’я хоста містить пробіли, символи підкреслення або інший неприпустимий для мітки DNS символ, OpenClaw використовує резервне значення openclaw.local. Задайте OPENCLAW_MDNS_HOSTNAME=<name> перед запуском Gateway, якщо потрібна явна мітка хоста.

​
Налагодження на вузлі iOS

Вузол iOS використовує NWBrowser для виявлення _openclaw-gw._tcp. Щоб зібрати журнали: Settings -> Gateway -> Advanced -> Discovery Debug Logs, потім Settings -> Gateway -> Advanced -> Discovery Logs -> відтворіть проблему -> Copy. Журнал містить переходи станів браузера та зміни набору результатів.

​
Коли вмикати Bonjour

Bonjour автоматично запускається під час запуску Gateway з порожньою конфігурацією на хостах macOS, оскільки локальний застосунок і сусідні вузли iOS/Android зазвичай покладаються на виявлення в межах однієї LAN. Увімкніть його явно, коли автоматичне виявлення в межах однієї LAN корисне в Linux, Windows або на іншому хості не з macOS:
Коли Bonjour увімкнено, він використовує discovery.mdns.mode, щоб визначити обсяг метаданих TXT для публікації; той самий режим керує необов’язковими підказками TXT у записах широкозонного DNS-SD. Режими:

​
Коли вимикати Bonjour

Залишайте Bonjour вимкненим, коли багатоадресні оголошення в LAN непотрібні, недоступні або шкідливі — типовими випадками є сервери не з macOS, мережа мосту Docker, WSL або мережева політика, яка відкидає багатоадресні пакети mDNS. Gateway залишається доступним через опубліковану URL-адресу, SSH, Tailnet або широкозонний DNS-SD; ненадійним стає лише автоматичне виявлення в LAN. Використовуйте перевизначення через змінну середовища для проблем, пов’язаних із конкретним розгортанням (це безпечно для образів Docker, файлів служб, сценаріїв запуску й одноразового налагодження — воно зникає разом із середовищем):
Використовуйте конфігурацію Plugin, якщо навмисно хочете вимкнути вбудований Plugin виявлення в LAN для цієї конфігурації OpenClaw:

​
Особливості 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

Якщо після налаштування Docker вузол більше не виявляє Gateway автоматично:
  1. Перевірте, у якому режимі працює Gateway: автоматичному, примусово ввімкненому чи примусово вимкненому:
  2. Переконайтеся, що сам Gateway доступний через опублікований порт:
  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, перевірте багатоадресне передавання з хоста:
    Якщо список результатів порожній або журнали Gateway показують повторювані помилки зондування ciao, відновіть OPENCLAW_DISABLE_BONJOUR=1 і використовуйте прямий маршрут або маршрут Tailnet.

​
Поширені режими відмови

  • Bonjour не працює між мережами: використовуйте Tailnet або SSH.
  • Багатоадресне передавання заблоковано: деякі мережі Wi-Fi вимикають mDNS.
  • Оголошувач завис на етапі перевірки/оголошення: вузли із заблокованим багатоадресним передаванням, мостові мережі контейнерів, WSL або частими змінами інтерфейсів можуть залишити відповідач у неоголошеному стані. Gateway залишається доступним через прямі маршрути, SSH, Tailnet або глобальну DNS-SD; вимкніть Bonjour у локальній мережі за допомогою discovery.mdns.mode: "off" або OPENCLAW_DISABLE_BONJOUR=1, якщо багатоадресне передавання недоступне.
  • Мостова мережа Docker: Bonjour автоматично вимикається у виявлених контейнерах. Установлюйте OPENCLAW_DISABLE_BONJOUR=0 лише для мережі хоста, macvlan або іншої мережі з підтримкою mDNS.
  • Перехід у режим сну/зміни інтерфейсів: macOS може тимчасово втрачати результати mDNS; повторіть спробу.
  • Перегляд працює, але визначення адреси не вдається: використовуйте прості імена машин (уникайте емодзі та розділових знаків), а потім перезапустіть Gateway. Ім’я екземпляра служби походить від імені хоста, тому надто складні імена можуть заплутати деякі засоби визначення адрес.

​
Екрановані імена екземплярів (\032)

Bonjour/DNS-SD часто екранує байти в іменах екземплярів служб як десяткові послідовності \DDD (пробіли перетворюються на \032). Це нормально на рівні протоколу; інтерфейси користувача мають декодувати їх для відображення (iOS використовує BonjourEscapes.decode).

​
Увімкнення / вимкнення / конфігурація

На вузлах macOS вбудований Plugin виявлення в локальній мережі за замовчуванням запускається автоматично. Коли Plugin Bonjour увімкнено, а OPENCLAW_DISABLE_BONJOUR не задано, Bonjour публікує оголошення на звичайних вузлах і автоматично вимикається у виявлених контейнерах (машинах Docker, Fly.io та поширених середовищах виконання контейнерів).

​
Пов’язана документація