OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Виявлення Bonjour

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

json5
{  gateway: { bind: "tailnet" }, // лише tailnet (рекомендовано)  discovery: { wideArea: { enabled: true, domain: "openclaw.internal" } },}

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

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

bash
openclaw dns setup --apply

Ця команда доступна лише в macOS і потребує Homebrew та активного підключення Tailscale. Вона встановлює CoreDNS (brew install coredns) і налаштовує його так, щоб він:

  • прослуховував порт 53 лише на інтерфейсах Tailscale хоста Gateway
  • обслуговував вибраний домен (приклад: openclaw.internal.) із ~/.openclaw/dns/<domain>.db

Спочатку запустіть без --apply, щоб переглянути план (домен, шлях до файлу зони, виявлену IP-адресу Tailnet, рекомендовану конфігурацію), нічого не встановлюючи.

Перевірте з комп’ютера, підключеного до Tailnet:

bash
dns-sd -B _openclaw-gw._tcp openclaw.internal.dig @&lt;TAILNET_IPV4&gt; -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Налаштування 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 (несекретні підказки)

Ключ Коли наявний
role=gateway Завжди.
displayName=<friendly name> Завжди.
lanHost=<hostname>.local Завжди.
gatewayPort=<port> Завжди (WS + HTTP Gateway).
transport=gateway Завжди.
gatewayTls=1 Лише коли ввімкнено TLS.
gatewayTlsSha256=<sha256> Лише коли ввімкнено TLS і доступний відбиток.
gatewayDirectReachable=1 Лише коли Gateway доступний безпосередньо (не лише через шлях ретранслятора/проксі).
canvasPort=<port> Лише коли ввімкнено хост полотна; наразі збігається з gatewayPort.
tailnetDns=<magicdns> Лише повний режим mDNS; необов’язкова підказка, коли доступний Tailnet.
sshPort=<port> Лише повний режим; пропускається в мінімальному та вимкненому режимах.
cliPath=<path> Лише повний режим; пропускається в мінімальному та вимкненому режимах.

Примітки щодо безпеки:

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

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

Вбудовані інструменти:

bash
# Перегляд екземплярівdns-sd -B _openclaw-gw._tcp local. # Розпізнавання одного екземпляра (замініть <instance>)dns-sd -L "<instance>" _openclaw-gw._tcp local.

Якщо перегляд працює, але розпізнавання завершується помилкою, зазвичай причина в політиці 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:

bash
openclaw plugins enable bonjour

Коли Bonjour увімкнено, він використовує discovery.mdns.mode, щоб визначити обсяг метаданих TXT для публікації; той самий режим керує необов’язковими підказками TXT у записах широкозонного DNS-SD. Режими:

Режим Поведінка
minimal (типово) Лише основні ключі TXT; без sshPort, cliPath, tailnetDns.
full Додає sshPort, cliPath, tailnetDns — використовуйте, коли клієнтам потрібні ці підказки.
off Пригнічує багатоадресне передавання в LAN, не змінюючи стан увімкнення Plugin; широкозонний DNS-SD усе ще може публікувати мінімальний маяк, коли discovery.wideArea.enabled має значення true.

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

Залишайте Bonjour вимкненим, коли багатоадресні оголошення в LAN непотрібні, недоступні або шкідливі — типовими випадками є сервери не з macOS, мережа мосту Docker, WSL або мережева політика, яка відкидає багатоадресні пакети mDNS. Gateway залишається доступним через опубліковану URL-адресу, SSH, Tailnet або широкозонний DNS-SD; ненадійним стає лише автоматичне виявлення в LAN.

Використовуйте перевизначення через змінну середовища для проблем, пов’язаних із конкретним розгортанням (це безпечно для образів Docker, файлів служб, сценаріїв запуску й одноразового налагодження — воно зникає разом із середовищем):

bash
OPENCLAW_DISABLE_BONJOUR=1

Використовуйте конфігурацію Plugin, якщо навмисно хочете вимкнути вбудований Plugin виявлення в LAN для цієї конфігурації OpenClaw:

bash
openclaw plugins disable bonjour

Особливості 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: автоматичному, примусово ввімкненому чи примусово вимкненому:

    bash
    docker compose config | grep OPENCLAW_DISABLE_BONJOUR

  2. Переконайтеся, що сам Gateway доступний через опублікований порт:

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

  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, перевірте багатоадресне передавання з хоста:

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

    Якщо список результатів порожній або журнали 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).

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

Налаштування Ефект
openclaw plugins enable bonjour Вмикає вбудований Plugin виявлення в локальній мережі на вузлах, де його не ввімкнено за замовчуванням.
openclaw plugins disable bonjour Вимикає багатоадресне оголошення в локальній мережі, вимикаючи вбудований Plugin.
OPENCLAW_DISABLE_BONJOUR=1 (або true/yes/on) Вимикає багатоадресне оголошення в локальній мережі без зміни конфігурації Plugin.
OPENCLAW_DISABLE_BONJOUR=0 (або false/no/off) Примусово вмикає багатоадресне оголошення в локальній мережі, зокрема у виявлених контейнерах.
discovery.mdns.mode off | minimal (за замовчуванням) | full — див. режими вище.
gateway.bind Керує режимом прив’язування Gateway у ~/.openclaw/openclaw.json.
OPENCLAW_SSH_PORT Перевизначає порт SSH, коли оголошується sshPort (повний режим).
OPENCLAW_TAILNET_DNS Публікує підказку MagicDNS у TXT, коли ввімкнено повний режим mDNS.
OPENCLAW_CLI_PATH Перевизначає оголошений шлях CLI (повний режим).

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

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

Was this useful?
On this page

On this page