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: встроенный плагин 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) по умолчанию привязывается к интерфейсу обратной петли. Для доступа через LAN/Tailnet явно задайте привязку и оставьте аутентификацию включённой. Для конфигураций только с Tailnet задайте gateway.bind: "tailnet" в ~/.openclaw/openclaw.json и перезапустите Gateway (или приложение строки меню macOS).

Что публикует объявления

Только Gateway публикует _openclaw-gw._tcp. Многоадресные объявления в LAN при включении поступают от встроенного плагина 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> Только когда включён узел canvas; сейчас совпадает с 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. Если требуется явная метка узла, задайте 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, не меняя состояние плагина; глобальный DNS-SD по-прежнему может публиковать минимальный маяк, когда discovery.wideArea.enabled равно true.

Когда следует отключать Bonjour

Оставляйте Bonjour отключённым, если многоадресные объявления в LAN не нужны, недоступны или вредны — типичные случаи: серверы без macOS, сеть Docker типа bridge, WSL или сетевая политика, блокирующая многоадресную рассылку mDNS. Gateway остаётся доступен через опубликованный URL, SSH, Tailnet или глобальный DNS-SD; ненадёжным становится только автоматическое обнаружение в LAN.

Используйте переопределение через переменную среды для проблем конкретного развёртывания (безопасно для образов Docker, файлов служб, сценариев запуска и разовой отладки — оно исчезает вместе с окружением):

bash
OPENCLAW_DISABLE_BONJOUR=1

Используйте конфигурацию плагина, если намеренно хотите отключить встроенный плагин обнаружения в LAN для этой конфигурации OpenClaw:

bash
openclaw plugins disable bonjour

Особенности Docker

Встроенный плагин Bonjour автоматически отключает многоадресные объявления в LAN в обнаруженных контейнерах, если OPENCLAW_DISABLE_BONJOUR не задано. Сети Docker типа bridge обычно не пересылают многоадресный трафик 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 Node перестал автоматически обнаруживать 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
    • Клиенты в других сетях: MagicDNS Tailnet, IP-адрес Tailnet, туннель SSH или глобальный DNS-SD

  4. Если вы намеренно включили плагин 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 или частыми изменениями интерфейсов средство объявления 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 Включает встроенный плагин обнаружения в локальной сети на хостах, где он не включён по умолчанию.
openclaw plugins disable bonjour Отключает многоадресное объявление в локальной сети путём отключения встроенного плагина.
OPENCLAW_DISABLE_BONJOUR=1 (или true/yes/on) Отключает многоадресное объявление в локальной сети без изменения конфигурации плагина.
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 встроенный плагин обнаружения в локальной сети по умолчанию запускается автоматически. Когда плагин Bonjour включён, а OPENCLAW_DISABLE_BONJOUR не задан, Bonjour публикует объявления на обычных хостах и автоматически отключается внутри обнаруженных контейнеров (Docker, машины Fly.io и распространённые среды выполнения контейнеров).

Связанные документы

Was this useful?
On this page

On this page