Сетевое взаимодействие и обнаружение

Обнаружение Bonjour

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

Bonjour между сетями (Unicast DNS‑SD) через Tailscale

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

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

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

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

{
  gateway: { bind: "tailnet" }, // только tailnet (рекомендуется)
  discovery: { wideArea: { enabled: true } }, // включает публикацию 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:

  • Добавьте сервер имён, указывающий на Tailnet IP шлюза (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=<friendly name>
  • lanHost=<hostname>.local
  • gatewayPort=<port> (WS + HTTP шлюза)
  • gatewayTls=1 (только когда TLS включён)
  • gatewayTlsSha256=<sha256> (только когда TLS включён и доступен отпечаток)
  • canvasPort=<port> (только когда хост canvas включён; в настоящее время совпадает с gatewayPort)
  • sshPort=<port> (по умолчанию 22, если не переопределён)
  • transport=gateway
  • cliPath=<path> (опционально; абсолютный путь к исполняемой точке входа openclaw)
  • tailnetDns=<magicdns> (опциональная подсказка, когда Tailnet доступен)

Примечания по безопасности:

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

Отладка на 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. Для захвата логов:

  • Настройки → Шлюз → Дополнительно → Логи отладки обнаружения
  • Настройки → Шлюз → Дополнительно → Логи обнаружения → воспроизведите → Копировать

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

Распространённые причины сбоев

  • 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).

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

Обнаружение и транспортыУдалённый доступ