> ## 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.

# Обнаружение и транспортные механизмы

OpenClaw решает две связанные, но разные задачи обнаружения:

1. **Удалённое управление оператором**: приложение в строке меню macOS управляет Gateway, работающим на другом компьютере.
2. **Сопряжение Node**: iOS/Android (и будущие Node) находят Gateway и безопасно сопрягаются с ним.

Все функции сетевого обнаружения и объявления находятся в **Node Gateway**
(`openclaw gateway`); клиенты (приложение macOS, iOS) только используют их.

## Термины

* **Gateway**: единый долгоживущий процесс, который управляет состоянием (сеансами,
  сопряжением, реестром Node) и запускает каналы. В большинстве конфигураций используется один процесс на хост;
  также возможны изолированные конфигурации с несколькими Gateway.
* **Gateway WS (уровень управления)**: конечная точка WebSocket, по умолчанию расположенная на `127.0.0.1:18789`;
  привяжите её к LAN/tailnet через `gateway.bind`.
* **Прямой транспорт WS**: конечная точка Gateway WS, доступная из LAN/tailnet (без SSH).
* **Транспорт SSH (резервный вариант)**: удалённое управление посредством перенаправления
  `127.0.0.1:18789` через SSH.
* **Устаревший мост TCP (удалён)**: прежний транспорт Node (см.
  [Протокол моста](https://docs2.openclaw.ai/ru/gateway/bridge-protocol)); он больше не объявляется для
  обнаружения и не входит в текущие сборки.

Сведения о протоколах: [Протокол Gateway](https://docs2.openclaw.ai/ru/gateway/protocol.md),
[Протокол моста (устаревший)](https://docs2.openclaw.ai/ru/gateway/bridge-protocol).

## Зачем нужны и прямое подключение, и SSH

* **Прямой WS** обеспечивает наиболее удобную работу в одной сети и внутри tailnet: автоматическое
  обнаружение в LAN через Bonjour, управление токенами сопряжения и ACL со стороны Gateway
  и отсутствие необходимости в доступе к командной оболочке.
* **SSH** — универсальный резервный вариант: работает везде, где есть доступ по SSH, даже
  между несвязанными сетями, не зависит от проблем с multicast/mDNS и не требует
  дополнительных входящих портов помимо SSH.

## Источники обнаружения

### 1) Bonjour / DNS-SD

Multicast Bonjour работает по принципу максимальных усилий и не действует между сетями. OpenClaw также
поддерживает поиск того же маяка Gateway через настроенный домен глобального DNS-SD,
поэтому обнаружение может охватывать как `local.` в той же LAN, так и настроенный
домен unicast DNS-SD для обнаружения между сетями.

**Gateway** объявляет свою конечную точку WS через Bonjour, когда включён встроенный
плагин `bonjour`; клиенты выполняют поиск и отображают список «выберите Gateway»,
а затем сохраняют выбранную конечную точку.

Устранение неполадок и сведения о маяке: [Bonjour](https://docs2.openclaw.ai/ru/gateway/bonjour.md).

#### Сведения о служебном маяке

* Тип службы: `_openclaw-gw._tcp` (маяк транспорта Gateway).
* Ключи TXT (не секретные):

  | Ключ | Примечания |
  | - | - |
  | `role=gateway` | Присутствует всегда. |
  | `transport=gateway` | Присутствует всегда. |
  | `displayName=<name>` | Отображаемое имя, настроенное оператором. |
  | `lanHost=<hostname>.local` | Только для объявления mDNS в LAN; не записывается глобальным DNS-SD. |
  | `gatewayPort=18789` | Порт Gateway WS и HTTP. |
  | `gatewayTls=1` | Только когда включён TLS. |
  | `gatewayTlsSha256=<sha256>` | Только когда включён TLS и доступен отпечаток. |
  | `tailnetDns=<magicdns>` | Необязательная подсказка; определяется автоматически, когда доступен Tailscale. |
  | `sshPort=<port>` | Присутствует только при `discovery.mdns.mode="full"`; отсутствует (SSH по умолчанию использует `22`) в стандартном режиме `"minimal"` как в объявлении LAN, так и в глобальном DNS-SD. |
  | `cliPath=<path>` | Использует то же условие `discovery.mdns.mode="full"`, что и `sshPort`; подсказка о пути CLI для удалённой установки. |

  Ключ TXT `canvasPort` определён в контракте обнаружения плагина для
  будущего порта хоста холста, но текущие пути кода не задают для него значение, поэтому
  сейчас он никогда не публикуется.

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

* Записи TXT Bonjour/mDNS **не проходят проверку подлинности**. Клиенты должны рассматривать значения TXT
  только как подсказки для интерфейса.
* При маршрутизации (хост/порт) следует отдавать предпочтение **разрешённой конечной точке службы**
  (SRV + A/AAAA), а не значениям `lanHost`, `tailnetDns` или `gatewayPort` из TXT.
* При закреплении TLS объявленное значение `gatewayTlsSha256` никогда не должно переопределять
  ранее сохранлённое закрепление.
* Перед сохранением отпечатка впервые Node iOS/Android должны запрашивать явное подтверждение
  «доверять этому отпечатку» (с проверкой по независимому каналу),
  если выбранный маршрут является защищённым или основан на TLS.

Включение, отключение и переопределение:

* `openclaw plugins enable bonjour` включает multicast-объявление в LAN.
* `discovery.mdns.mode` в `openclaw.json` управляет трансляцией mDNS:
  `"minimal"` (по умолчанию), `"full"` (добавляет `cliPath`/`sshPort` как в маяк
  LAN, так и в любую глобальную зону DNS-SD) или `"off"` (отключает mDNS).
* `OPENCLAW_DISABLE_BONJOUR=1` принудительно отключает объявления; `discovery.mdns.mode="off"`
  отключает их независимо. `OPENCLAW_DISABLE_BONJOUR=0` — явное
  согласие, переопределяющее автоматическое отключение плагина внутри обнаруженного контейнера
  (Docker, containerd, Kubernetes, LXC); оно не переопределяет
  `discovery.mdns.mode="off"`. Встроенный плагин `bonjour` автоматически запускается на
  хостах macOS (`enabledByDefaultOnPlatforms: ["darwin"]`) и автоматически отключается
  внутри обнаруженных контейнеров; для Linux, Windows и других контейнерных
  развёртываний требуется явно указать `plugins enable bonjour`.
* `gateway.bind` в `~/.openclaw/openclaw.json` управляет режимом привязки Gateway.
* `OPENCLAW_SSH_PORT` переопределяет объявляемый порт SSH (действует только
  при `discovery.mdns.mode="full"`).
* `OPENCLAW_TAILNET_DNS` публикует подсказку `tailnetDns` (MagicDNS).
* `OPENCLAW_CLI_PATH` переопределяет объявляемый путь CLI.

### 2) Tailnet (между сетями)

Для Gateway в разных физических сетях Bonjour не поможет.
Рекомендуемая цель для прямого подключения — имя Tailscale MagicDNS (предпочтительно) или
стабильный IP-адрес tailnet.

Если Gateway определяет, что работает под управлением Tailscale, он публикует
`tailnetDns` как необязательную подсказку для клиентов (включая глобальные маяки).
Приложение macOS при обнаружении Gateway предпочитает имена MagicDNS необработанным
IP-адресам Tailscale, что обеспечивает надёжность при изменении IP-адресов tailnet
(перезапусках Node, переназначении CGNAT), поскольку MagicDNS автоматически разрешается
в текущий IP-адрес.

При сопряжении мобильных Node подсказки обнаружения никогда не ослабляют транспортную безопасность
на маршрутах tailnet/общедоступной сети:

* iOS/Android по-прежнему требуют защищённый маршрут первого подключения через tailnet/общедоступную сеть
  (`wss://` или Tailscale Serve/Funnel).
* Обнаруженный необработанный IP-адрес tailnet — это подсказка для маршрутизации, а не разрешение использовать
  незашифрованный удалённый `ws://`.
* Прямое подключение `ws://` в частной LAN по-прежнему поддерживается.
* Для наиболее простого пути Tailscale на мобильных Node используйте Tailscale Serve, чтобы
  обнаружение и настройка разрешались в одну и ту же защищённую конечную точку MagicDNS.

### 3) Ручная цель / цель SSH

Если прямой маршрут отсутствует (или прямое подключение отключено), клиенты всегда могут
подключиться через SSH, перенаправив локальный порт Gateway. См.
[Удалённый доступ](https://docs2.openclaw.ai/ru/gateway/remote.md).

## Выбор транспорта (политика клиента)

1. Если настроенная сопряжённая конечная точка прямого подключения доступна, используйте её.
2. Иначе, если обнаружение находит Gateway в `local.` или в настроенном глобальном
   домене, предложите выбор «Использовать этот Gateway» одним нажатием и сохраните его как
   конечную точку прямого подключения.
3. Иначе, если настроен DNS/IP tailnet, попробуйте прямое подключение. Для мобильных Node на
   маршрутах tailnet/общедоступной сети прямое подключение означает защищённую конечную точку, а не незашифрованный
   удалённый `ws://`.
4. Иначе используйте SSH как резервный вариант.

## Сопряжение и аутентификация (прямой транспорт)

Gateway является источником достоверных данных для допуска Node/клиентов:

* Запросы на сопряжение создаются, одобряются и отклоняются в Gateway (см.
  [Сопряжение Gateway](https://docs2.openclaw.ai/ru/gateway/pairing.md)).
* Gateway обеспечивает аутентификацию (токен/пара ключей), области доступа/ACL (это не необработанный
  прокси ко всем методам) и ограничения частоты запросов.

## Обязанности компонентов

* **Gateway**: объявляет маяки обнаружения, управляет решениями о сопряжении, размещает
  конечную точку WS.
* **Приложение macOS**: помогает выбрать Gateway, отображает запросы сопряжения, использует SSH
  только как резервный вариант.
* **Node iOS/Android**: для удобства выполняют поиск через Bonjour и подключаются к
  сопряжённому Gateway WS.

## См. также

* [Удалённый доступ](https://docs2.openclaw.ai/ru/gateway/remote.md)
* [Tailscale](https://docs2.openclaw.ai/ru/gateway/tailscale.md)
* [Обнаружение Bonjour](https://docs2.openclaw.ai/ru/gateway/bonjour.md)