---
read_when:
    - Отладка проблем с обнаружением Bonjour в macOS/iOS
    - Изменение типов служб mDNS, записей TXT или интерфейса обнаружения
summary: Обнаружение и отладка Bonjour/mDNS (маяки Gateway, клиенты и распространённые режимы отказа)
title: Обнаружение Bonjour
x-i18n:
    generated_at: "2026-07-16T16:23:30Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 42a46dc34e94dc86ee0432b12fcb59b3855371c745d79825a00aa557e1369160
    source_path: gateway/bonjour.md
    workflow: 16
---

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 @<TAILNET_IPV4> -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 и распространённые среды выполнения контейнеров).

## Связанная документация

- Политика обнаружения и выбор транспорта: [Обнаружение](/ru/gateway/discovery)
- Сопряжение Node и подтверждения: [Сопряжение Gateway](/ru/gateway/pairing)
