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 і потребуючи явного ввімкнення в Linux, Windows та контейнеризованих розгортаннях Gateway. Той самий маяк також можна публікувати через налаштований домен глобального 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) за замовчуванням прив’язується до local 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 cancellation ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...
  • bonjour: disabling advertiser after ... failed restarts ...

Сторожовий механізм вважає активні стани probing, announcing і нещодавні перейменування через конфлікти станами виконання. Якщо служба так і не досягає стану announced, OpenClaw повторно створює оголошувач, а після неодноразових збоїв вимикає Bonjour для цього процесу Gateway замість нескінченного повторного оголошення.

Bonjour використовує системне ім’я хоста для оголошеного хоста .local, якщо воно є дійсною DNS-міткою. Якщо системне ім’я хоста містить пробіли, символи підкреслення або інший символ, недійсний для DNS-мітки, OpenClaw використовує резервне значення openclaw.local. Якщо потрібна явна мітка хоста, перед запуском Gateway задайте OPENCLAW_MDNS_HOSTNAME=<name>.

Налагодження на вузлі 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 вимкнено:

    • Інтерфейс керування або локальні засоби: http://127.0.0.1:18789
    • Клієнти LAN: http://<gateway-host>:18789
    • Клієнти з інших мереж: MagicDNS Tailnet, 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.
  • Multicast заблоковано: деякі мережі Wi-Fi вимикають mDNS.
  • Оголошувач застряг на етапі перевірки/оголошення: хости із заблокованим multicast, контейнерними мостами, WSL або частими змінами інтерфейсів можуть залишити оголошувач ciao у стані без оголошення. OpenClaw повторює спробу кілька разів, а потім вимикає Bonjour для поточного процесу Gateway замість нескінченного перезапуску оголошувача.
  • Мережа через міст 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 виявлення в LAN на хостах, де його не ввімкнено за замовчуванням.
openclaw plugins disable bonjour Вимикає multicast-оголошення в LAN шляхом вимкнення вбудованого Plugin.
OPENCLAW_DISABLE_BONJOUR=1 (або true/yes/on) Вимикає multicast-оголошення в LAN без зміни конфігурації Plugin.
OPENCLAW_DISABLE_BONJOUR=0 (або false/no/off) Примусово вмикає multicast-оголошення в LAN, зокрема всередині виявлених контейнерів.
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 виявлення в LAN за замовчуванням запускається автоматично. Коли Plugin Bonjour увімкнено, а OPENCLAW_DISABLE_BONJOUR не задано, Bonjour публікує оголошення на звичайних хостах і автоматично вимикається всередині виявлених контейнерів (Docker, машини Fly.io та поширені середовища виконання контейнерів).

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

Was this useful?
On this page

On this page