Перейти к основному содержанию

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

В 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); больше не анонсируется для обнаружения.
Детали протоколов:

​
Почему мы сохраняем и «прямой», и 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)
Примечания по безопасности:
  • Записи Bonjour/mDNS TXT не аутентифицированы. Клиенты должны рассматривать значения TXT только как подсказки для UX.
  • Маршрутизация (host/port) должна отдавать предпочтение разрешённой конечной точке сервиса (SRV + A/AAAA), а не переданным через TXT значениям lanHost, tailnetDns или gatewayPort.
  • TLS pinning никогда не должен позволять рекламируемому gatewayTlsSha256 переопределять ранее сохранённый pin.
  • Узлы iOS/Android должны рассматривать прямые подключения, полученные через discovery, как только TLS и требовать явного подтверждения «доверять этому отпечатку» перед сохранением pin при первом подключении (внеполосная проверка).
Отключение/переопределение:
  • 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.