English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Виявлення та транспортні механізми

OpenClaw має дві окремі проблеми, які на поверхні виглядають схожими:

  1. Віддалене керування оператором: застосунок у меню macOS керує Gateway, що працює в іншому місці.
  2. Сполучення Node: iOS/Android (і майбутні Node) знаходять Gateway і безпечно сполучаються.

Мета дизайну — тримати все мережеве виявлення/оголошення в Node Gateway (openclaw gateway), а клієнтів (mac app, iOS) залишати споживачами.

Терміни

  • Gateway: один довготривалий процес 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 (див. Протокол bridge); більше не оголошується для виявлення і більше не входить до поточних збірок.

Деталі протоколу:

Чому ми зберігаємо і прямий доступ, і SSH

  • Direct WS забезпечує найкращий UX у тій самій мережі та в межах tailnet:
    • автоматичне виявлення в LAN через Bonjour
    • токени сполучення + ACL, якими володіє Gateway
    • доступ до оболонки не потрібен; поверхня протоколу може залишатися вузькою й придатною для аудиту
  • SSH залишається універсальним резервним варіантом:
    • працює всюди, де у вас є SSH-доступ (навіть між непов’язаними мережами)
    • переживає проблеми multicast/mDNS
    • не потребує нових вхідних портів, окрім SSH

Вхідні дані виявлення (як клієнти дізнаються, де Gateway)

1) Виявлення Bonjour / DNS-SD

Multicast Bonjour працює за принципом best-effort і не проходить між мережами. OpenClaw також може переглядати той самий маяк Gateway через налаштований домен wide-area DNS-SD, тож виявлення може охоплювати:

  • local. у тій самій LAN
  • налаштований unicast DNS-SD домен для виявлення між мережами

Цільовий напрям:

  • Gateway оголошує свою WS-кінцеву точку через Bonjour, коли ввімкнено вбудований Plugin bonjour. Plugin автоматично запускається на хостах macOS і вмикається вручну в інших середовищах.
  • Клієнти переглядають і показують список "виберіть Gateway", а потім зберігають вибрану кінцеву точку.

Усунення несправностей і деталі маяка: Bonjour.

Деталі маяка сервісу

  • Типи сервісів:
    • _openclaw-gw._tcp (маяк транспорту Gateway)
  • TXT-ключі (несекретні):
    • role=gateway
    • transport=gateway
    • displayName=<friendly name> (відображуване ім’я, налаштоване оператором)
    • lanHost=<hostname>.local
    • gatewayPort=18789 (Gateway WS + HTTP)
    • gatewayTls=1 (лише коли TLS увімкнено)
    • gatewayTlsSha256=<sha256> (лише коли TLS увімкнено і відбиток доступний)
    • 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-пінінг ніколи не повинен дозволяти оголошеному gatewayTlsSha256 замінювати раніше збережений pin.
  • Node iOS/Android мають вимагати явного підтвердження "довіряти цьому відбитку" перед збереженням першого pin (позасмугова перевірка), коли вибраний маршрут є secure/TLS-based.

Увімкнення/вимкнення/перевизначення:

  • openclaw plugins enable bonjour вмикає LAN multicast-оголошення.
  • 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 не допоможе. Рекомендована "пряма" ціль:

  • DNS-ім’я Tailscale MagicDNS (бажано) або стабільна tailnet IP.

Якщо Gateway може визначити, що працює під Tailscale, він публікує tailnetDns як необов’язкову підказку для клієнтів (зокрема wide-area маяків).

Застосунок macOS тепер віддає перевагу іменам MagicDNS над сирими IP Tailscale для виявлення Gateway. Це підвищує надійність, коли tailnet IP змінюються (наприклад, після перезапуску Node або повторного призначення CGNAT), бо імена MagicDNS автоматично розв’язуються в поточну IP.

Для сполучення мобільних Node підказки виявлення не послаблюють безпеку транспорту на tailnet/public маршрутах:

  • iOS/Android усе ще потребують безпечного шляху першого підключення tailnet/public (wss:// або Tailscale Serve/Funnel).
  • Виявлена сира tailnet IP — це підказка маршрутизації, а не дозвіл використовувати plaintext remote ws://.
  • Пряме підключення ws:// у приватній LAN лишається підтримуваним.
  • Якщо потрібен найпростіший шлях Tailscale для мобільних Node, використовуйте Tailscale Serve, щоб і виявлення, і setup code розв’язувалися в ту саму безпечну кінцеву точку MagicDNS.

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

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

Див. Віддалений доступ.

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

Рекомендована поведінка клієнта:

  1. Якщо налаштована й доступна сполучена пряма кінцева точка, використовуйте її.
  2. Інакше, якщо виявлення знаходить Gateway на local. або в налаштованому wide-area домені, запропонуйте вибір "Використати цей Gateway" в один дотик і збережіть його як пряму кінцеву точку.
  3. Інакше, якщо налаштовано tailnet DNS/IP, спробуйте прямий доступ. Для мобільних Node на tailnet/public маршрутах direct означає безпечну кінцеву точку, а не plaintext remote ws://.
  4. Інакше перейдіть на SSH.

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

Gateway є джерелом істини для допуску Node/клієнта.

  • Запити на сполучення створюються/схвалюються/відхиляються в Gateway (див. Сполучення Gateway).
  • Gateway забезпечує:
    • автентифікацію (token / keypair)
    • scopes/ACL (Gateway не є сирим proxy до кожного методу)
    • rate limits

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

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

Пов’язане