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

OpenClaw имеет две различные проблемы, которые выглядят похожими на поверхности:

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

Цель проектирования — сохранить все сетевое обнаружение/рекламу в шлюзе узлов (openclaw gateway) и держать клиентов (приложение mac, iOS) в качестве потребителей.

Термины

  • Шлюз: один долгоживущий процесс шлюза, который владеет состоянием (сессии, сопряжение, реестр узлов) и запускает каналы. Большинство настроек используют один на хост; возможны изолированные мультишлюзовые настройки.
  • 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 (устарел/удален): старый транспорт узла (см. Протокол моста); больше не рекламируется для обнаружения.

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

Почему мы сохраняем оба "прямой" и SSH

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

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

1) Bonjour / mDNS (только локальная сеть)

Bonjour оптимистичен и не пересекает сети. Он используется только для удобства "в той же локальной сети".

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

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

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

Детали маяка службы

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

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

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

2) Tailnet (межсетевой)

Для настроек в стиле Лондон/Вена Bonjour не поможет. Рекомендуемая "прямая" цель:

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

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

3) Ручной / цель SSH

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

См. Удаленный доступ.

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

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

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

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

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

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

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

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