Перейти до основного вмісту

​
Виявлення та транспорти

В OpenClaw є дві різні задачі, які на поверхні виглядають схожими:
  1. Віддалене керування оператором: застосунок рядка меню macOS керує gateway, що працює деінде.
  2. Парування вузлів: iOS/Android (і майбутні вузли) знаходять gateway і безпечно виконують парування.
Мета дизайну — тримати все мережеве виявлення/оголошення в Node Gateway (openclaw gateway) і залишати клієнтів (mac app, iOS) лише споживачами.

​
Терміни

  • Gateway: один довготривалий процес gateway, який володіє станом (сесії, парування, реєстр вузлів) і запускає канали. У більшості налаштувань використовується один на хост; можливі ізольовані налаштування з кількома gateway.
  • Gateway WS (control plane): кінцева точка WebSocket, типово на 127.0.0.1:18789; може бути прив’язана до LAN/tailnet через gateway.bind.
  • Транспорт Direct WS: кінцева точка Gateway WS, доступна з LAN/tailnet (без SSH).
  • Транспорт SSH (резервний варіант): віддалене керування через проброс 127.0.0.1:18789 поверх SSH.
  • Legacy TCP bridge (видалено): старіший транспорт вузлів (див. Bridge protocol); більше не оголошується для виявлення і більше не входить до поточних збірок.
Докладно про протоколи:

​
Чому ми зберігаємо і “direct”, і SSH

  • Direct 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.
  • Клієнти переглядають і показують список “виберіть gateway”, а потім зберігають вибрану кінцеву точку.
Докладно про усунення проблем і beacon: Bonjour.

​
Докладно про 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 host; зараз це той самий gatewayPort, коли canvas host увімкнено)
    • 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), а не значенням TXT lanHost, tailnetDns чи gatewayPort.
  • TLS pinning ніколи не повинен дозволяти оголошеному gatewayTlsSha256 перевизначати раніше збережений pin.
  • Вузли iOS/Android повинні вимагати явного підтвердження “довіряти цьому fingerprint”, перш ніж зберігати pin під час першого підключення (позасмугова перевірка), коли обраний маршрут є безпечним/з TLS.
Вимкнення/перевизначення:
  • OPENCLAW_DISABLE_BONJOUR=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 не допоможе. Рекомендована ціль “direct”:
  • ім’я Tailscale MagicDNS (бажано) або стабільний tailnet IP.
Якщо gateway може визначити, що працює під Tailscale, він публікує tailnetDns як необов’язкову підказку для клієнтів (включно з wide-area beacon). Тепер macOS app віддає перевагу іменам MagicDNS над сирими IP-адресами Tailscale для виявлення gateway. Це покращує надійність, коли tailnet IP змінюються (наприклад, після перезапусків вузлів або перепризначення CGNAT), тому що імена MagicDNS автоматично розв’язуються в поточну IP-адресу. Для парування мобільних вузлів підказки виявлення не послаблюють безпеку транспорту на tailnet/публічних маршрутах:
  • Для iOS/Android все одно потрібен безпечний маршрут першого підключення через tailnet/публічну мережу (wss:// або Tailscale Serve/Funnel).
  • Виявлена сира tailnet IP — це підказка для маршрутизації, а не дозвіл використовувати віддалений незашифрований ws://.
  • Пряме підключення ws:// у приватній LAN і далі підтримується.
  • Якщо вам потрібен найпростіший шлях Tailscale для мобільних вузлів, використовуйте Tailscale Serve, щоб і виявлення, і код налаштування розв’язувалися до тієї самої безпечної кінцевої точки MagicDNS.

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

Коли прямого маршруту немає (або direct вимкнено), клієнти завжди можуть підключитися через SSH, пробросивши loopback-порт gateway. Див. Remote access.

​
Вибір транспорту (політика клієнта)

Рекомендована поведінка клієнта:
  1. Якщо налаштовано спарену пряму кінцеву точку і вона доступна, використовуйте її.
  2. Інакше, якщо виявлення знаходить gateway у local. або в налаштованому wide-area домені, запропонуйте вибір “Use this gateway” в один дотик і збережіть її як пряму кінцеву точку.
  3. Інакше, якщо налаштовано tailnet DNS/IP, спробуйте direct. Для мобільних вузлів на tailnet/публічних маршрутах direct означає безпечну кінцеву точку, а не віддалений незашифрований ws://.
  4. Інакше перейдіть до SSH.

​
Парування + автентифікація (прямий транспорт)

Gateway є джерелом істини для допуску вузлів/клієнтів.
  • Запити на парування створюються/схвалюються/відхиляються в gateway (див. Gateway pairing).
  • Gateway забезпечує:
    • автентифікацію (token / keypair)
    • scope/ACL (gateway — це не сирий проксі до будь-якого методу)
    • обмеження швидкості

​
Відповідальність за компонентами

  • Gateway: оголошує beacon виявлення, володіє рішеннями щодо парування та хостить кінцеву точку WS.
  • macOS app: допомагає вибрати gateway, показує запити на парування і використовує SSH лише як резервний варіант.
  • Вузли iOS/Android: переглядають Bonjour як зручну можливість і підключаються до спареного Gateway WS.