Обнаружение и транспорты¶

В OpenClaw есть две разные задачи, которые на первый взгляд выглядят одинаково:

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

Цель проектирования — держать всё сетевое обнаружение/анонсирование в Node Gateway (openclaw gateway) и оставить клиентов (mac‑приложение, iOS) в роли потребителей.

Условия¶

• 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‑мост (deprecated/removed): старый транспорт узлов (см. Bridge protocol); больше не анонсируется для обнаружения.

Детали протоколов:

• Gateway protocol
• Bridge protocol (legacy)

Почему мы сохраняем и «прямой», и SSH¶

• Прямой WS — лучший UX в одной сети и внутри tailnet:
• автообнаружение в LAN через Bonjour
• токены подключения + ACL, принадлежащие шлюзу
• не требуется доступ к shell; поверхность протокола остаётся узкой и аудируемой
• SSH остаётся универсальным резервным вариантом:
• работает везде, где есть доступ по SSH (даже между несвязанными сетями)
• переживает проблемы с multicast/mDNS
• не требует открытия новых входящих портов, кроме SSH

Источники обнаружения (как клиенты узнают, где находится шлюз)¶

1. Bonjour / mDNS (только LAN)¶

Bonjour работает по принципу best‑effort и не пересекает сети. Используется только для удобства «в одной LAN».

Целевое направление:

• шлюз анонсирует свою конечную точку WS через Bonjour.
• Клиенты просматривают и показывают список «выберите шлюз», затем сохраняют выбранную конечную точку.

Устранение неполадок и детали маяков: Bonjour.

Детали сервисного маяка¶

• Типы сервисов:
• _openclaw-gw._tcp (маяк транспорта шлюза)
• TXT‑ключи (несекретные):
• role=gateway
• lanHost=<hostname>.local
• sshPort=22 (или то, что анонсируется)
• gatewayPort=18789 (Gateway WS + HTTP)
• gatewayTls=1 (только когда включён TLS)
• gatewayTlsSha256=<sha256> (только когда включён TLS и доступен отпечаток)
• canvasPort=18793 (порт хоста canvas по умолчанию; обслуживает /__openclaw__/canvas/)
• cliPath=<path> (необязательно; абсолютный путь к исполняемому openclaw entrypoint или бинарнику)
• tailnetDns=<magicdns> (необязательная подсказка; автоопределяется при наличии Tailscale)

Отключение/переопределение:

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

2. Tailnet (межсетевое)¶

Для конфигураций типа «Лондон/Вена» Bonjour не поможет. Рекомендуемая «прямая» цель:

• имя Tailscale MagicDNS (предпочтительно) или стабильный IP в tailnet.

Если шлюз может определить, что он запущен под Tailscale, он публикует tailnetDns как необязательную подсказку для клиентов (включая широкозонные маяки).

3. Ручная цель / SSH¶

Когда прямого маршрута нет (или прямой режим отключён), клиенты всегда могут подключиться через SSH, пробросив порт шлюза local loopback.

См. Remote access.

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

Рекомендуемое поведение клиента:

1. Если настроена и достижима сопряжённая прямая конечная точка — использовать её.
2. Иначе, если Bonjour находит шлюз в LAN, предложить вариант «Использовать этот шлюз» одним касанием и сохранить его как прямую конечную точку.
3. Иначе, если настроен DNS/IP tailnet — попробовать прямое подключение.
4. Иначе — перейти к SSH.

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

Шлюз — источник истины для допуска узлов/клиентов.

• Запросы на сопряжение создаются/утверждаются/отклоняются в шлюзе (см. Gateway pairing).
• Силы шлюза:
• аутентификацию (токен / пара ключей)
• области доступа/ACL (шлюз — не «сырой» прокси ко всем методам)
• лимиты по ставкам

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

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