OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

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

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 (см. Протокол моста); он больше не объявляется для обнаружения и не входит в текущие сборки.

Сведения о протоколах: Протокол Gateway, Протокол моста (устаревший).

Зачем нужны и прямое подключение, и 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.

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

  • Тип службы: _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. См. Удалённый доступ.

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

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

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

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

  • Запросы на сопряжение создаются, одобряются и отклоняются в Gateway (см. Сопряжение Gateway).
  • Gateway обеспечивает аутентификацию (токен/пара ключей), области доступа/ACL (это не необработанный прокси ко всем методам) и ограничения частоты запросов.

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

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

См. также

Was this useful?
On this page

On this page