> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Обнаружение Bonjour OpenClaw может использовать Bonjour (mDNS / DNS-SD) для обнаружения активного Gateway (конечной точки WebSocket). Обзор multicast `local.` — это **удобство только для LAN**. Встроенный Plugin `bonjour` отвечает за LAN-анонсирование. Он автоматически запускается на хостах macOS и включается явно в Linux, Windows и контейнеризированных развертываниях Gateway. Для обнаружения между сетями тот же beacon также можно публиковать через настроенный wide-area домен DNS-SD. Обнаружение по-прежнему работает по принципу best-effort и **не** заменяет подключение через SSH или Tailnet. ## Wide-area Bonjour (Unicast DNS-SD) через Tailscale Если узел и Gateway находятся в разных сетях, multicast mDNS не пройдет через границу. Можно сохранить тот же UX обнаружения, переключившись на **unicast DNS-SD** ("Wide-Area Bonjour") через Tailscale. Общие шаги: 1. Запустите DNS-сервер на хосте Gateway (доступном через Tailnet). 2. Опубликуйте записи DNS-SD для `_openclaw-gw._tcp` в выделенной зоне (пример: `openclaw.internal.`). 3. Настройте **split DNS** в Tailscale, чтобы выбранный домен разрешался через этот DNS-сервер для клиентов (включая iOS). OpenClaw поддерживает любой домен обнаружения; `openclaw.internal.` — только пример. Узлы iOS/Android просматривают и `local.`, и настроенный wide-area домен. ### Конфигурация Gateway (рекомендуется) ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { gateway: { bind: "tailnet" }, // tailnet-only (recommended) discovery: { wideArea: { enabled: true } }, // enables wide-area DNS-SD publishing } ``` ### Однократная настройка DNS-сервера (хост Gateway) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw dns setup --apply ``` Это устанавливает CoreDNS и настраивает его так, чтобы он: * слушал порт 53 только на интерфейсах Tailscale у Gateway * обслуживал выбранный домен (пример: `openclaw.internal.`) из `~/.openclaw/dns/.db` Проверьте с машины, подключенной к Tailnet: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} dns-sd -B _openclaw-gw._tcp openclaw.internal. dig @ -p 53 _openclaw-gw._tcp.openclaw.internal PTR +short ``` ### Настройки DNS в Tailscale В консоли администратора Tailscale: * Добавьте nameserver, указывающий на tailnet IP Gateway (UDP/TCP 53). * Добавьте split DNS, чтобы домен обнаружения использовал этот nameserver. После того как клиенты примут DNS Tailnet, узлы iOS и обнаружение CLI смогут просматривать `_openclaw-gw._tcp` в вашем домене обнаружения без multicast. ### Безопасность слушателя Gateway (рекомендуется) Порт WS Gateway (по умолчанию `18789`) по умолчанию привязывается к loopback. Для доступа из LAN/tailnet явно задайте привязку и оставьте аутентификацию включенной. Для конфигураций только через tailnet: * Установите `gateway.bind: "tailnet"` в `~/.openclaw/openclaw.json`. * Перезапустите Gateway (или перезапустите приложение строки меню macOS). ## Что анонсируется Только Gateway анонсирует `_openclaw-gw._tcp`. LAN multicast-анонсирование предоставляется встроенным Plugin `bonjour`, когда Plugin включен; wide-area публикация DNS-SD остается в зоне ответственности Gateway. ## Типы сервисов * `_openclaw-gw._tcp` - beacon транспорта Gateway (используется узлами macOS/iOS/Android). ## Ключи TXT (несекретные подсказки) Gateway анонсирует небольшие несекретные подсказки, чтобы упростить UI-потоки: * `role=gateway` * `displayName=` * `lanHost=.local` * `gatewayPort=` (Gateway WS + HTTP) * `gatewayTls=1` (только когда TLS включен) * `gatewayTlsSha256=` (только когда TLS включен и fingerprint доступен) * `canvasPort=` (только когда хост canvas включен; сейчас совпадает с `gatewayPort`) * `transport=gateway` * `tailnetDns=` (только полный режим mDNS, необязательная подсказка, когда Tailnet доступен) * `sshPort=` (только полный режим; отсутствует в минимальном и выключенном режимах) * `cliPath=` (только полный режим; отсутствует в минимальном и выключенном режимах) Примечания по безопасности: * Записи TXT Bonjour/mDNS **не аутентифицированы**. Клиенты не должны считать TXT авторитетным источником маршрутизации. * Клиенты должны маршрутизировать через разрешенную конечную точку сервиса (SRV + A/AAAA). Считайте `lanHost`, `tailnetDns`, `gatewayPort` и `gatewayTlsSha256` только подсказками. * Автоматический выбор SSH-цели также должен использовать разрешенный хост сервиса, а не только подсказки TXT. * TLS pinning никогда не должен позволять анонсированному `gatewayTlsSha256` переопределять ранее сохраненный pin. * Узлы iOS/Android должны считать прямые подключения на основе обнаружения **только TLS** и требовать явного подтверждения пользователя перед доверием первому fingerprint. ## Отладка на macOS Полезные встроенные инструменты: * Просмотреть экземпляры: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} dns-sd -B _openclaw-gw._tcp local. ``` * Разрешить один экземпляр (замените ``): ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} dns-sd -L "" _openclaw-gw._tcp local. ``` Если просмотр работает, а разрешение нет, обычно причина в политике LAN или проблеме резолвера mDNS. ## Отладка в логах Gateway Gateway пишет rolling log file (при запуске выводится как `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 ...` Watchdog считает активные состояния `probing`, `announcing` и свежие conflict-renames состояниями в процессе выполнения. Если сервис так и не достигает `announced`, OpenClaw в итоге пересоздает advertiser и после повторяющихся сбоев отключает Bonjour для этого процесса Gateway вместо бесконечного повторного анонсирования. Bonjour использует системное имя хоста для анонсируемого хоста `.local`, когда оно является допустимой DNS-меткой. Если системное имя хоста содержит пробелы, подчеркивания или другой недопустимый символ DNS-метки, OpenClaw откатывается к `openclaw.local`. Задайте `OPENCLAW_MDNS_HOSTNAME=` перед запуском Gateway, когда нужна явная метка хоста. ## Отладка на узле iOS Узел iOS использует `NWBrowser` для обнаружения `_openclaw-gw._tcp`. Чтобы собрать логи: * Settings → Gateway → Advanced → **Discovery Debug Logs** * Settings → Gateway → Advanced → **Discovery Logs** → воспроизведите → **Copy** Лог включает переходы состояний browser и изменения набора результатов. ## Когда включать Bonjour Bonjour автоматически запускается при старте Gateway с пустой конфигурацией на хостах macOS, потому что локальное приложение и близлежащие узлы iOS/Android обычно зависят от обнаружения в той же LAN. Включайте Bonjour явно, когда автоматическое обнаружение в той же LAN полезно в Linux, Windows или на другом хосте не macOS: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins enable bonjour ``` Когда Bonjour включен, он использует `discovery.mdns.mode`, чтобы решить, сколько метаданных TXT публиковать. Тот же режим управляет необязательными TXT-подсказками в wide-area записях DNS-SD. Режим по умолчанию — `minimal`; используйте `full` только когда клиентам нужны подсказки `cliPath` или `sshPort`. Используйте `off`, чтобы подавить LAN multicast без изменения включения Plugin; wide-area DNS-SD все еще может публиковать минимальный beacon Gateway, когда `discovery.wideArea.enabled` равно true. ## Когда отключать Bonjour Оставляйте Bonjour отключенным, когда LAN multicast-анонсирование не нужно, недоступно или вредно. Типичные случаи — серверы не macOS, сеть Docker bridge, WSL или сетевая политика, которая отбрасывает multicast mDNS. В таких средах Gateway по-прежнему доступен через опубликованный URL, SSH, Tailnet или wide-area DNS-SD, но LAN-автообнаружение ненадежно. Предпочитайте существующее переопределение через окружение, когда проблема относится к развертыванию: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_DISABLE_BONJOUR=1 ``` Это отключает LAN multicast-анонсирование без изменения конфигурации Plugin. Это безопасно для образов Docker, service-файлов, скриптов запуска и разовой отладки, потому что настройка исчезает вместе с окружением. Используйте конфигурацию Plugin, когда намеренно хотите выключить встроенный LAN Plugin обнаружения для этой конфигурации OpenClaw: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins disable bonjour ``` ## Особенности Docker Встроенный Plugin Bonjour автоматически отключает LAN multicast-анонсирование в обнаруженных контейнерах, когда `OPENCLAW_DISABLE_BONJOUR` не задан. Сети Docker bridge обычно не пересылают multicast mDNS (`224.0.0.251:5353`) между контейнером и LAN, поэтому анонсирование из контейнера редко заставляет обнаружение работать. Важные особенности: * Bonjour автоматически запускается на хостах macOS и включается явно в остальных средах. Если оставить его отключенным, Gateway не остановится; будет пропущено только LAN multicast-анонсирование. * Отключение Bonjour не меняет `gateway.bind`; Docker по-прежнему по умолчанию использует `OPENCLAW_GATEWAY_BIND=lan`, чтобы опубликованный порт хоста мог работать. * Отключение Bonjour не отключает wide-area DNS-SD. Используйте wide-area discovery или Tailnet, когда Gateway и узел находятся не в одной LAN. * Повторное использование того же `OPENCLAW_CONFIG_DIR` вне Docker не сохраняет политику автоотключения контейнера. * Задавайте `OPENCLAW_DISABLE_BONJOUR=0` только для host networking, macvlan или другой сети, где известно, что multicast mDNS проходит; задавайте `1` для принудительного отключения. ## Устранение неполадок отключенного Bonjour Если узел больше не обнаруживает Gateway автоматически после настройки Docker: 1. Проверьте, в каком режиме работает Gateway: auto, forced-on или forced-off: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} docker compose config | grep OPENCLAW_DISABLE_BONJOUR ``` 2. Проверьте, что сам Gateway доступен через опубликованный порт: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} curl -fsS http://127.0.0.1:18789/healthz ``` 3. Используйте прямую цель, когда Bonjour отключен: * Control UI или локальные инструменты: `http://127.0.0.1:18789` * LAN-клиенты: `http://:18789` * Клиенты между сетями: Tailnet MagicDNS, Tailnet IP, SSH tunnel или wide-area DNS-SD 4. Если вы намеренно включили Plugin Bonjour в Docker и принудительно включили анонсирование через `OPENCLAW_DISABLE_BONJOUR=0`, проверьте multicast с хоста: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} dns-sd -B _openclaw-gw._tcp local. ``` Если просмотр пуст или логи Gateway показывают повторяющиеся отмены ciao watchdog, восстановите `OPENCLAW_DISABLE_BONJOUR=1` и используйте прямой маршрут или маршрут Tailnet. ## Распространенные режимы отказа * **Bonjour не пересекает сети**: используйте Tailnet или SSH. * **Multicast заблокирован**: некоторые сети Wi-Fi отключают mDNS. * **Advertiser завис в probing/announcing**: хосты с заблокированным multicast, контейнерные bridge-сети, WSL или смена интерфейсов могут оставить advertiser ciao в состоянии non-announced. OpenClaw повторяет попытки несколько раз, а затем отключает Bonjour для текущего процесса Gateway вместо бесконечного перезапуска advertiser. * **Сеть Docker bridge**: Bonjour автоматически отключается в обнаруженных контейнерах. Задавайте `OPENCLAW_DISABLE_BONJOUR=0` только для host, macvlan или другой сети с поддержкой mDNS. * **Сон / смена интерфейсов**: macOS может временно терять результаты mDNS; повторите попытку. * **Просмотр работает, но разрешение завершается ошибкой**: используйте простые имена машин (избегайте emoji и пунктуации), затем перезапустите Gateway. Имя экземпляра сервиса производно от имени хоста, поэтому слишком сложные имена могут сбивать с толку некоторые резолверы. ## Экранированные имена экземпляров (`\032`) Bonjour/DNS-SD часто экранирует байты в именах экземпляров сервисов как десятичные последовательности `\DDD` (например, пробелы становятся `\032`). * Это нормально на уровне протокола. * UI должны декодировать для отображения (iOS использует `BonjourEscapes.decode`). ## Включение / отключение / конфигурация * Хосты macOS по умолчанию автоматически запускают встроенный Plugin обнаружения в LAN. * `openclaw plugins enable bonjour` включает встроенный Plugin обнаружения в LAN на хостах, где он не включен по умолчанию. * `openclaw plugins disable bonjour` отключает многоадресную рекламу LAN, отключая встроенный Plugin. * `OPENCLAW_DISABLE_BONJOUR=1` отключает многоадресную рекламу LAN без изменения конфигурации Plugin; допустимые истинные значения: `1`, `true`, `yes` и `on` (устаревшее: `OPENCLAW_DISABLE_BONJOUR`). * `OPENCLAW_DISABLE_BONJOUR=0` принудительно включает многоадресную рекламу LAN, включая обнаруженные контейнеры; допустимые ложные значения: `0`, `false`, `no` и `off`. * Когда Bonjour Plugin включен, а `OPENCLAW_DISABLE_BONJOUR` не задан, Bonjour публикует рекламу на обычных хостах и автоматически отключается внутри обнаруженных контейнеров. * `gateway.bind` в `~/.openclaw/openclaw.json` управляет режимом привязки Gateway. * `OPENCLAW_SSH_PORT` переопределяет SSH-порт, когда публикуется `sshPort` (устаревшее: `OPENCLAW_SSH_PORT`). * `OPENCLAW_TAILNET_DNS` публикует подсказку MagicDNS в TXT, когда включен полный режим mDNS (устаревшее: `OPENCLAW_TAILNET_DNS`). * `OPENCLAW_CLI_PATH` переопределяет публикуемый путь CLI (устаревшее: `OPENCLAW_CLI_PATH`). ## Связанные документы * Политика обнаружения и выбор транспорта: [Обнаружение](/ru/gateway/discovery) * Сопряжение Node + подтверждения: [Сопряжение Gateway](/ru/gateway/pairing)