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

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

Только Gateway публикует объявления _openclaw-gw._tcp. Многоадресные объявления в локальной сети при включении поступают от встроенного плагина 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.

Если просмотр работает, но разрешение завершается ошибкой, обычно проблема связана с политикой локальной сети или резолвером 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 обычно полагаются на обнаружение в одной локальной сети.

Включите его явно, если автоматическое обнаружение в одной локальной сети полезно на 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 Подавляет многоадресную рассылку в локальной сети, не меняя состояние плагина; глобальная DNS-SD по-прежнему может публиковать минимальный маяк, когда discovery.wideArea.enabled имеет значение true.

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

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

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

bash
OPENCLAW_DISABLE_BONJOUR=1

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

bash
openclaw plugins disable bonjour

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

Встроенный плагин Bonjour автоматически отключает многоадресные объявления в локальной сети в обнаруженных контейнерах, когда OPENCLAW_DISABLE_BONJOUR не задан. Мостовые сети Docker обычно не передают многоадресный трафик mDNS (224.0.0.251:5353) между контейнером и локальной сетью, поэтому объявления из контейнера редко обеспечивают работу обнаружения.

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

  • Bonjour автоматически запускается на хостах macOS, а на остальных включается по запросу. Если оставить его отключенным, Gateway не остановится — будут пропущены лишь многоадресные объявления в локальной сети.
  • Отключение Bonjour не изменяет gateway.bind; в Docker по-прежнему по умолчанию используется OPENCLAW_GATEWAY_BIND=lan, поэтому опубликованный порт хоста работает.
  • Отключение Bonjour не отключает глобальную DNS-SD. Используйте глобальное обнаружение или Tailnet, когда Gateway и Node находятся не в одной локальной сети.
  • Повторное использование того же 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
    • Клиенты локальной сети: http://<gateway-host>:18789
    • Клиенты из других сетей: Tailnet MagicDNS, 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 или частыми изменениями интерфейсов ответчик может остаться в состоянии без объявления. Gateway остаётся доступным напрямую, через SSH, Tailnet или глобальные маршруты DNS-SD; если многоадресная рассылка недоступна, отключите Bonjour в локальной сети с помощью discovery.mdns.mode: "off" или OPENCLAW_DISABLE_BONJOUR=1.
  • Сеть Docker bridge: в обнаруженных контейнерах 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