Перейти к основному содержанию
OpenClaw решает две разные проблемы, которые на поверхности выглядят похожими:
  1. Удаленное управление оператором: приложение в строке меню macOS управляет Gateway, запущенным в другом месте.
  2. Сопряжение узлов: iOS/Android (и будущие узлы) находят Gateway и безопасно сопрягаются с ним.
Цель дизайна — держать все сетевое обнаружение/объявление в Node Gateway (openclaw gateway), а клиентов (приложение mac, iOS) оставить потребителями.

​
Термины

  • Gateway: один долгоживущий процесс Gateway, который владеет состоянием (сеансы, сопряжение, реестр узлов) и запускает каналы. В большинстве установок используется один процесс на хост; изолированные установки с несколькими Gateway возможны.
  • Gateway WS (плоскость управления): конечная точка WebSocket на 127.0.0.1:18789 по умолчанию; может быть привязана к LAN/tailnet через gateway.bind.
  • Прямой транспорт WS: обращенная к LAN/tailnet конечная точка Gateway WS (без SSH).
  • Транспорт SSH (резервный вариант): удаленное управление через проброс 127.0.0.1:18789 по SSH.
  • Устаревший TCP-мост (удален): старый транспорт узлов (см. протокол моста); больше не объявляется для обнаружения и больше не входит в текущие сборки.
Подробности протоколов:

​
Почему мы сохраняем и прямое подключение, и SSH

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

​
Входные данные обнаружения (как клиенты узнают, где находится Gateway)

​
1) Обнаружение Bonjour / DNS-SD

Multicast Bonjour работает по принципу best-effort и не пересекает границы сетей. OpenClaw также может просматривать тот же beacon Gateway через настроенный домен wide-area DNS-SD, поэтому обнаружение может охватывать:
  • local. в той же LAN
  • настроенный домен unicast DNS-SD для обнаружения между сетями
Целевое направление:
  • Gateway объявляет свою конечную точку WS через Bonjour, когда включен встроенный Plugin bonjour. Plugin автоматически запускается на хостах macOS и включается явно в других средах.
  • Клиенты просматривают и показывают список «выбрать Gateway», затем сохраняют выбранную конечную точку.
Устранение неполадок и подробности beacon: Bonjour.

​
Подробности service beacon

  • Типы служб:
    • _openclaw-gw._tcp (beacon транспорта Gateway)
  • Ключи TXT (не секретные):
    • role=gateway
    • transport=gateway
    • displayName=<friendly name> (отображаемое имя, настроенное оператором)
    • lanHost=<hostname>.local
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (только когда TLS включен)
    • gatewayTlsSha256=<sha256> (только когда TLS включен и fingerprint доступен)
    • canvasPort=<port> (порт хоста canvas; сейчас совпадает с gatewayPort, когда хост canvas включен)
    • tailnetDns=<magicdns> (необязательная подсказка; определяется автоматически, когда доступен Tailscale)
    • sshPort=<port> (только полный режим mDNS; wide-area DNS-SD может опускать его, и тогда значения SSH по умолчанию остаются 22)
    • cliPath=<path> (только полный режим mDNS; wide-area DNS-SD все равно записывает его как подсказку удаленной установки)
Примечания по безопасности:
  • TXT-записи Bonjour/mDNS не аутентифицированы. Клиенты должны считать значения TXT только подсказками для UX.
  • Маршрутизация (host/port) должна предпочитать разрешенную конечную точку службы (SRV + A/AAAA) значениям lanHost, tailnetDns или gatewayPort, предоставленным через TXT.
  • Закрепление TLS никогда не должно позволять объявленному gatewayTlsSha256 переопределять ранее сохраненный pin.
  • Узлы iOS/Android должны требовать явного подтверждения «доверять этому fingerprint» перед сохранением pin в первый раз (внеполосная проверка), когда выбранный маршрут основан на secure/TLS.
Включение/отключение/переопределение:
  • openclaw plugins enable bonjour включает multicast-объявление в LAN.
  • OPENCLAW_DISABLE_BONJOUR=1 отключает объявление.
  • Когда Plugin Bonjour включен и OPENCLAW_DISABLE_BONJOUR не задан, Bonjour объявляется на обычных хостах и автоматически отключается внутри обнаруженных контейнеров. Запуск Gateway на macOS с пустой конфигурацией включает Plugin автоматически; Linux, Windows и контейнеризованные развертывания требуют явного включения. Используйте 0 только на host, macvlan или другой сети с поддержкой mDNS; используйте 1, чтобы принудительно отключить.
  • gateway.bind в ~/.openclaw/openclaw.json управляет режимом привязки Gateway.
  • OPENCLAW_SSH_PORT переопределяет объявляемый порт SSH, когда выводится sshPort.
  • OPENCLAW_TAILNET_DNS публикует подсказку tailnetDns (MagicDNS).
  • OPENCLAW_CLI_PATH переопределяет объявляемый путь CLI.

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

Для установок в стиле London/Vienna Bonjour не поможет. Рекомендуемая «прямая» цель:
  • имя Tailscale MagicDNS (предпочтительно) или стабильный IP tailnet.
Если Gateway может определить, что он запущен под Tailscale, он публикует tailnetDns как необязательную подсказку для клиентов (включая wide-area beacon). Приложение macOS теперь предпочитает имена MagicDNS сырым IP Tailscale при обнаружении Gateway. Это повышает надежность при изменении IP tailnet (например, после перезапуска узла или переназначения CGNAT), потому что имена MagicDNS автоматически разрешаются в текущий IP. Для сопряжения мобильных узлов подсказки обнаружения не ослабляют безопасность транспорта на маршрутах tailnet/public:
  • iOS/Android по-прежнему требуют безопасный путь первого подключения tailnet/public (wss:// или Tailscale Serve/Funnel).
  • Обнаруженный сырой IP tailnet — это подсказка маршрутизации, а не разрешение использовать plaintext удаленный ws://.
  • Прямое подключение ws:// в частной LAN остается поддерживаемым.
  • Если вам нужен самый простой путь Tailscale для мобильных узлов, используйте Tailscale Serve, чтобы и обнаружение, и код настройки разрешались в одну и ту же безопасную конечную точку MagicDNS.

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

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

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

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

​
Сопряжение + auth (прямой транспорт)

Gateway — источник истины для допуска узлов/клиентов.
  • Запросы на сопряжение создаются/одобряются/отклоняются в Gateway (см. сопряжение Gateway).
  • Gateway обеспечивает:
    • auth (токен / keypair)
    • scopes/ACL (Gateway не является сырым прокси ко всем методам)
    • ограничения скорости

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

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

​
Связанные материалы