Gateway

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

OpenClaw має дві пов’язані, але різні проблеми виявлення:

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

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

Терміни

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

Докладно про протоколи: Протокол 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, коли ввімкнено вбудований Plugin 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 визначено в контракті виявлення Plugin для майбутнього порту хоста полотна, але жоден поточний шлях коду не задає значення, тому наразі він ніколи не передається.

Примітки щодо безпеки:

Записи TXT Bonjour/mDNS не автентифіковані. Клієнти мають розглядати значення TXT лише як підказки для взаємодії з користувачем.
Для маршрутизації (хост/порт) слід надавати перевагу визначеній кінцевій точці служби (SRV + A/AAAA), а не наданим через TXT значенням lanHost, tailnetDns або gatewayPort.
Закріплення TLS ніколи не повинно дозволяти оголошеному gatewayTlsSha256 перевизначати раніше збережений відбиток.
Вузли 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 — це явна згода, яка перевизначає автоматичне вимкнення Plugin усередині виявленого контейнера (Docker, containerd, Kubernetes, LXC); вона не перевизначає discovery.mdns.mode="off". Вбудований Plugin 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 як необов’язкову підказку для клієнтів (зокрема через глобальні маяки). Для виявлення Gateway застосунок macOS надає перевагу іменам MagicDNS, а не необробленим IP-адресам Tailscale. Це забезпечує надійність у разі зміни IP-адрес tailnet (перезапусків вузлів, перепризначення CGNAT), оскільки MagicDNS автоматично визначає поточну IP-адресу.

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

iOS/Android усе одно потребують захищеного шляху першого підключення через tailnet або публічну мережу (wss:// або Tailscale Serve/Funnel).
Виявлена необроблена IP-адреса tailnet є підказкою для маршрутизації, а не дозволом використовувати незашифрований віддалений ws://.
Пряме підключення через приватну LAN за допомогою ws:// і надалі підтримується.
Для найпростішого шляху Tailscale на мобільних вузлах використовуйте Tailscale Serve, щоб і виявлення, і налаштування вели до тієї самої захищеної кінцевої точки MagicDNS.

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

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

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

Якщо налаштована й доступна сполучена пряма кінцева точка, використовуйте її.
Інакше, якщо виявлення знаходить Gateway у local. або в налаштованому глобальному домені, запропонуйте вибір одним дотиком «Використовувати цей Gateway» і збережіть його як пряму кінцеву точку.
Інакше, якщо налаштовано DNS/IP tailnet, спробуйте пряме підключення. Для мобільних вузлів на маршрутах tailnet або публічних маршрутах пряме підключення означає захищену кінцеву точку, а не незашифрований віддалений ws://.
Інакше використайте SSH як резервний варіант.

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

Gateway є джерелом істини щодо допуску вузлів і клієнтів:

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

Обов’язки компонентів

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

Пов’язані матеріали

Was this useful?