--- read_when: - Реалізація або зміна виявлення/анонсування Bonjour - Налаштування режимів віддаленого підключення (прямий або SSH) - Проєктування виявлення Node + сполучення для віддалених Node summary: Виявлення Node та транспортні механізми (Bonjour, Tailscale, SSH) для пошуку Gateway title: Виявлення та транспортні механізми x-i18n: generated_at: "2026-05-06T04:12:07Z" model: gpt-5.5 provider: openai source_hash: 7f53e1292d9e5b402186c48c777e7e665c790981a64679c783ae8d8a1f170ee1 source_path: gateway/discovery.md workflow: 16 --- 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](/uk/gateway/bridge-protocol)); більше не оголошується для виявлення і більше не входить до поточних збірок. Деталі протоколу: - [Протокол Gateway](/uk/gateway/protocol) - [Протокол bridge (застарілий)](/uk/gateway/bridge-protocol) ## Чому ми зберігаємо і прямий доступ, і 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](/uk/gateway/bonjour). #### Деталі маяка сервісу - Типи сервісів: - `_openclaw-gw._tcp` (маяк транспорту Gateway) - TXT-ключі (несекретні): - `role=gateway` - `transport=gateway` - `displayName=` (відображуване ім’я, налаштоване оператором) - `lanHost=.local` - `gatewayPort=18789` (Gateway WS + HTTP) - `gatewayTls=1` (лише коли TLS увімкнено) - `gatewayTlsSha256=` (лише коли TLS увімкнено і відбиток доступний) - `canvasPort=` (порт canvas host; наразі такий самий, як `gatewayPort`, коли canvas host увімкнено) - `tailnetDns=` (необов’язкова підказка; автоматично виявляється, коли доступний Tailscale) - `sshPort=` (лише повний режим mDNS; wide-area DNS-SD може його пропустити, і в такому разі лишаються типові значення SSH на `22`) - `cliPath=` (лише повний режим 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. Див. [Віддалений доступ](/uk/gateway/remote). ## Вибір транспорту (політика клієнта) Рекомендована поведінка клієнта: 1. Якщо налаштована й доступна сполучена пряма кінцева точка, використовуйте її. 2. Інакше, якщо виявлення знаходить Gateway на `local.` або в налаштованому wide-area домені, запропонуйте вибір "Використати цей Gateway" в один дотик і збережіть його як пряму кінцеву точку. 3. Інакше, якщо налаштовано tailnet DNS/IP, спробуйте прямий доступ. Для мобільних Node на tailnet/public маршрутах direct означає безпечну кінцеву точку, а не plaintext remote `ws://`. 4. Інакше перейдіть на SSH. ## Сполучення + автентифікація (прямий транспорт) Gateway є джерелом істини для допуску Node/клієнта. - Запити на сполучення створюються/схвалюються/відхиляються в Gateway (див. [Сполучення Gateway](/uk/gateway/pairing)). - Gateway забезпечує: - автентифікацію (token / keypair) - scopes/ACL (Gateway не є сирим proxy до кожного методу) - rate limits ## Відповідальність за компонентами - **Gateway**: оголошує маяки виявлення, володіє рішеннями щодо сполучення і хостить WS-кінцеву точку. - **macOS app**: допомагає вибрати Gateway, показує запити на сполучення і використовує SSH лише як резервний варіант. - **Node iOS/Android**: переглядають Bonjour для зручності й підключаються до сполученого Gateway WS. ## Пов’язане - [Віддалений доступ](/uk/gateway/remote) - [Tailscale](/uk/gateway/tailscale) - [Виявлення Bonjour](/uk/gateway/bonjour)