Bonjour / обнаружение mDNS

OpenClaw использует Bonjour (mDNS / DNS‑SD) в качестве удобства только для локальной сети для обнаружения активного шлюза (конечной точки WebSocket). Это оптимистичное решение и не заменяет подключение на основе SSH или Tailnet.

Wide‑area Bonjour (Unicast DNS‑SD) через Tailscale

Если узел и шлюз находятся в разных сетях, многоадресный mDNS не пересечет границу. Вы можете сохранить тот же UX обнаружения, переключившись на unicast DNS‑SD ("Wide‑Area Bonjour") через Tailscale.

Шаги высокого уровня:

  1. Запустите DNS-сервер на хосте шлюза (доступный через Tailnet).
  2. Опубликуйте записи DNS‑SD для _openclaw-gw._tcp в выделенной зоне (пример: openclaw.internal.).
  3. Настройте Tailscale split DNS, чтобы ваш выбранный домен разрешался через этот DNS-сервер для клиентов (включая iOS).

OpenClaw поддерживает любой домен обнаружения; openclaw.internal. — это просто пример. Узлы iOS/Android просматривают как local., так и ваш настроенный широкозонный домен.

Конфигурация шлюза (рекомендуется)

\{
  gateway: \{ bind: "tailnet" \}, // только tailnet (рекомендуется)
  discovery: \{ wideArea: \{ enabled: true \} \} // включает публикацию wide-area DNS-SD
\}

Единоразовая настройка DNS-сервера (хост шлюза)

openclaw dns setup --apply

Это устанавливает CoreDNS и настраивает его на:

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

Проверьте с машины, подключенной к tailnet:

dns-sd -B _openclaw-gw._tcp openclaw.internal.
dig @<TAILNET_IPV4> -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short

Настройки DNS Tailscale

В консоли администратора Tailscale:

  • Добавьте сервер имен, указывающий на IP tailnet шлюза (UDP/TCP 53).
  • Добавьте split DNS, чтобы ваш домен обнаружения использовал этот сервер имен.

После того как клиенты примут DNS tailnet, узлы iOS могут просматривать _openclaw-gw._tcp в вашем домене обнаружения без многоадресной рассылки.

Безопасность слушателя шлюза (рекомендуется)

Порт WS шлюза (по умолчанию 18789) по умолчанию привязан к loopback. Для доступа LAN/tailnet привяжите явно и держите аутентификацию включенной.

Для настроек только tailnet:

  • Установите gateway.bind: "tailnet" в ~/.openclaw/openclaw.json.
  • Перезапустите шлюз (или перезапустите приложение строки меню macOS).

Что рекламируется

Только шлюз рекламирует _openclaw-gw._tcp.

Типы служб

  • _openclaw-gw._tcp — маяк транспорта шлюза (используется узлами macOS/iOS/Android).

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

Шлюз рекламирует небольшие несекретные подсказки для удобства потоков UI:

  • role=gateway
  • displayName=<дружественное имя>
  • lanHost=<hostname>.local
  • gatewayPort=<port> (WS + HTTP шлюза)
  • gatewayTls=1 (только когда TLS включен)
  • gatewayTlsSha256=<sha256> (только когда TLS включен и отпечаток доступен)
  • canvasPort=<port> (только когда хост canvas включен; по умолчанию 18793)
  • sshPort=<port> (по умолчанию 22, когда не переопределено)
  • transport=gateway
  • cliPath=<path> (опционально; абсолютный путь к исполняемой точке входа openclaw)
  • tailnetDns=<magicdns> (опциональная подсказка, когда доступен Tailnet)

Отладка на macOS

Полезные встроенные инструменты:

  • Просмотр экземпляров: 
    dns-sd -B _openclaw-gw._tcp local.
  • Разрешение одного экземпляра (замените <instance>): 
    dns-sd -L "<instance>" _openclaw-gw._tcp local.

Если просмотр работает, но разрешение не удается, вы обычно сталкиваетесь с политикой LAN или проблемой резолвера mDNS.

Отладка в журналах шлюза

Шлюз записывает файл журнала с ротацией (печатается при запуске как gateway log file: ...). Ищите строки bonjour:, особенно:

  • bonjour: advertise failed ...
  • bonjour: ... name conflict resolved / hostname conflict resolved
  • bonjour: watchdog detected non-announced service ...

Отладка на узле iOS

Узел iOS использует NWBrowser для обнаружения _openclaw-gw._tcp.

Для захвата журналов:

  • Настройки → Шлюз → Расширенные → Discovery Debug Logs
  • Настройки → Шлюз → Расширенные → Discovery Logs → воспроизвести → Копировать

Журнал включает переходы состояний браузера и изменения набора результатов.

Распространенные режимы отказа

  • Bonjour не пересекает сети: используйте Tailnet или SSH.
  • Заблокирована многоадресная рассылка: некоторые Wi‑Fi сети отключают mDNS.
  • Сон / изменение интерфейса: macOS может временно удалять результаты mDNS; повторите попытку.
  • Просмотр работает, но разрешение не удается: сохраняйте имена машин простыми (избегайте эмодзи или пунктуации), затем перезапустите шлюз. Имя экземпляра службы происходит от имени хоста, поэтому слишком сложные имена могут запутать некоторые резолверы.

Экранированные имена экземпляров (\032)

Bonjour/DNS‑SD часто экранирует байты в именах экземпляров служб как десятичные последовательности \DDD (например, пробелы становятся \032).

  • Это нормально на уровне протокола.
  • UI должны декодировать для отображения (iOS использует BonjourEscapes.decode).

Отключение / конфигурация

  • OPENCLAW_DISABLE_BONJOUR=1 отключает рекламу (наследие: OPENCLAW_DISABLE_BONJOUR).
  • gateway.bind в ~/.openclaw/openclaw.json контролирует режим привязки шлюза.
  • OPENCLAW_SSH_PORT переопределяет порт SSH, рекламируемый в TXT (наследие: OPENCLAW_SSH_PORT).
  • OPENCLAW_TAILNET_DNS публикует подсказку MagicDNS в TXT (наследие: OPENCLAW_TAILNET_DNS).
  • OPENCLAW_CLI_PATH переопределяет рекламируемый путь CLI (наследие: OPENCLAW_CLI_PATH).

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

← Назад к документации