--- read_when: - Запуск або усунення несправностей у конфігураціях віддаленого Gateway summary: Віддалений доступ за допомогою Gateway WS, тунелів SSH і tailnet-мереж title: Віддалений доступ x-i18n: generated_at: "2026-07-12T13:14:39Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 78daaad7bcb9f80072eaa2d6946bff9f28ba1ec4f95a68edb0d24cf7f9c3fec2 source_path: gateway/remote.md workflow: 16 --- OpenClaw запускає один Gateway (головний) на хості та підключає до нього кожен клієнт. Gateway керує сеансами, профілями автентифікації, каналами та станом; усе інше є клієнтом. - **Оператори** (ви або застосунок macOS): пряме підключення WebSocket через LAN/Tailnet є найпростішим, коли Gateway доступний; тунелювання SSH — універсальний резервний варіант. - **Вузли** (iOS/Android та інші пристрої): підключаються до **WebSocket** Gateway (через LAN/tailnet або тунель SSH). ## Основна ідея За замовчуванням WebSocket Gateway прив’язується до **local loopback** на порту `18789` (`gateway.port`). Для віддаленого використання або відкрийте до нього доступ через Tailscale Serve / довірену прив’язку LAN-Tailnet, або перенаправте порт local loopback через SSH. ## Варіанти топології | Конфігурація | Де працює Gateway | Найкраще підходить для | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Постійно активний Gateway у вашій tailnet | Постійний хост (VPS або домашній сервер), доступний через Tailscale або SSH | Ноутбуків, які часто переходять у режим сну, але потребують постійно активного агента. Див. [exe.dev](/uk/install/exe-dev) (проста VM) або [Hetzner](/uk/install/hetzner) (робочий VPS). | | Домашній настільний комп’ютер | Настільний комп’ютер; ноутбук підключається віддалено через режим віддаленої роботи застосунку macOS (Налаштування → Підключення → Запуск OpenClaw) | Розміщення агента на обладнанні, яке залишається ввімкненим. Інструкція: [віддалений доступ у macOS](/uk/platforms/mac/remote). | | Ноутбук | Ноутбук із безпечним доступом через тунель SSH або Tailscale Serve (залиште `gateway.bind: "loopback"`) | Конфігурацій з одним комп’ютером. Див. [Tailscale](/uk/gateway/tailscale) і [вебінтерфейс](/uk/web). | Для конфігурацій із постійно активним Gateway і ноутбуком рекомендовано залишити `gateway.bind: "loopback"` та використовувати **Tailscale Serve** для інтерфейсу керування або довірену прив’язку LAN/Tailnet із `gateway.remote.transport: "direct"`. Тунель SSH — резервний варіант, який працює з будь-якого комп’ютера. ## Потік команд (що де виконується) Один Gateway керує станом і каналами; вузли є периферійними пристроями. Приклад (повідомлення Telegram спрямовується до інструмента вузла): 1. Повідомлення Telegram надходить до **Gateway**. 2. Gateway запускає **агента**, який вирішує, чи викликати інструмент вузла. 3. Gateway викликає **вузол** через WebSocket Gateway (RPC `node.invoke`). 4. Вузол повертає результат; Gateway відповідає в Telegram. Вузли не запускають службу Gateway. На одному хості має працювати лише один Gateway, якщо ви навмисно не запускаєте ізольовані профілі (див. [Кілька Gateway](/uk/gateway/multiple-gateways)). «Режим вузла» застосунку macOS — це лише клієнт вузла, що працює через WebSocket Gateway. ## Тунель SSH (CLI та інструменти) ```bash ssh -N -L 18789:127.0.0.1:18789 user@gateway-host ``` Коли тунель активний, `openclaw health` і `openclaw status --deep` звертаються до віддаленого Gateway через `ws://127.0.0.1:18789`. Команди `openclaw gateway status`, `openclaw gateway health`, `openclaw gateway probe` і `openclaw gateway call` також можуть використовувати перенаправлену URL-адресу через `--url`. Замініть `18789` на налаштоване значення `gateway.port` (або `--port` / `OPENCLAW_GATEWAY_PORT`). `--url` ніколи не використовує резервно облікові дані з конфігурації або середовища. Передайте `--token` або `--password` явно; без них клієнт не надсилає облікових даних, і підключення завершується помилкою, якщо цільовий Gateway вимагає автентифікації. ## Стандартні налаштування віддаленого CLI Збережіть віддалену ціль, щоб команди CLI використовували її за замовчуванням: ```json5 { gateway: { mode: "remote", remote: { url: "ws://127.0.0.1:18789", token: "your-token", }, }, } ``` Якщо Gateway доступний лише через local loopback, залиште URL-адресу `ws://127.0.0.1:18789` і спочатку відкрийте тунель SSH. У транспорті через тунель SSH застосунку macOS виявлене ім’я хоста Gateway указується в `gateway.remote.sshTarget` (`user@host` або `user@host:port`); `gateway.remote.url` залишається URL-адресою локального тунелю. Якщо віддалений порт відрізняється від локального, задайте `gateway.remote.remotePort`. Перевірка ключа хоста за замовчуванням є суворою (`gateway.remote.sshHostKeyPolicy: "strict"`). Задайте значення `"openssh"`, щоб натомість делегувати перевірку вашій чинній конфігурації OpenSSH; перед увімкненням перегляньте користувацькі та системні налаштування SSH. Для Gateway, який уже доступний у довіреній LAN або Tailnet, використовуйте прямий режим: ```json5 { gateway: { mode: "remote", remote: { transport: "direct", url: "ws://192.168.0.202:18789", token: "your-token", }, }, } ``` ## Пріоритет облікових даних Визначення облікових даних Gateway відбувається за єдиним спільним контрактом у шляхах виклику, перевірки та стану, а також під час моніторингу схвалення виконання в Discord. Хост вузла використовує той самий контракт з одним винятком для локального режиму (він ігнорує `gateway.remote.*`). - Явні облікові дані (`--token`, `--password` або `gatewayToken` інструмента) завжди мають пріоритет у шляхах виклику, які приймають явну автентифікацію. - Безпека перевизначення URL-адреси: - CLI `--url` ніколи не використовує неявні облікові дані з конфігурації або середовища. - `OPENCLAW_GATEWAY_URL` із середовища може використовувати лише облікові дані середовища (`OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`). - Стандартні налаштування локального режиму: - токен: `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token` (віддалене резервне значення лише тоді, коли локальний токен не задано) - пароль: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password` (віддалене резервне значення лише тоді, коли локальний пароль не задано) - Стандартні налаштування віддаленого режиму: - токен: `gateway.remote.token` -> `OPENCLAW_GATEWAY_TOKEN` -> `gateway.auth.token` - пароль: `OPENCLAW_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password` - Виняток локального режиму хоста вузла: `gateway.remote.token` / `gateway.remote.password` ігноруються. - Перевірки токена для віддалених запитів перевірки та стану за замовчуванням суворі: у віддаленому режимі вони використовують лише `gateway.remote.token` (без резервного локального токена). - Перевизначення Gateway через середовище використовують лише `OPENCLAW_GATEWAY_*`. ## Віддалений доступ до інтерфейсу чату WebChat не має окремого HTTP-порту; інтерфейс чату SwiftUI підключається безпосередньо до WebSocket Gateway. - Перенаправте `18789` через SSH (див. вище), а потім підключіть клієнти до `ws://127.0.0.1:18789`. - Для прямого режиму LAN/Tailnet підключіть клієнти до налаштованої приватної URL-адреси `ws://` або захищеної URL-адреси `wss://`. - У macOS режим віддаленої роботи застосунку автоматично керує вибраним транспортом. ## Режим віддаленої роботи застосунку macOS Застосунок у смузі меню macOS керує тією самою конфігурацією від початку до кінця: віддаленими перевірками стану, WebChat і пересиланням активації голосом. Інструкція: [віддалений доступ у macOS](/uk/platforms/mac/remote). ## Правила безпеки (віддалений доступ/VPN) Залишайте Gateway доступним **лише через local loopback**, якщо ви не впевнені, що вам потрібна інша прив’язка. - **Local loopback + SSH/Tailscale Serve** — найбезпечніше стандартне налаштування (без публічного доступу). - Незашифрований `ws://` приймається для local loopback, приватних адрес/LAN (RFC 1918), локальних адрес каналу, CGNAT, а також хостів `.local` і `.ts.net`. Публічні віддалені хости мають використовувати `wss://`. - **Прив’язки не до local loopback** (`lan`/`tailnet`/`custom` або `auto`, коли local loopback недоступний) мають використовувати автентифікацію Gateway: токен, пароль або зворотний проксі з урахуванням ідентичності та `gateway.auth.mode: "trusted-proxy"`. - `gateway.remote.token` / `.password` є джерелами облікових даних клієнта; самі по собі вони не налаштовують автентифікацію сервера. - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як резервне джерело лише тоді, коли `gateway.auth.*` не задано. - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef, але значення не вдалося визначити, операція завершується безпечною відмовою (без маскування через віддалене резервне значення). - `gateway.remote.tlsFingerprint` закріплює сертифікат TLS віддаленого сервера для `wss://`, зокрема в прямому режимі macOS. Без збереженого відбитка macOS закріплює його під час першого використання лише після успішної стандартної перевірки системної довіри; Gateway із самопідписаними сертифікатами або сертифікатами приватного центру сертифікації потребують явного відбитка або віддаленого доступу через SSH. - **Tailscale Serve** може автентифікувати трафік інтерфейсу керування/WebSocket за допомогою заголовків ідентичності, коли `gateway.auth.allowTailscale: true`. Кінцеві точки HTTP API не використовують цю автентифікацію за заголовками, натомість дотримуючись звичайного режиму HTTP-автентифікації Gateway. Цей процес без токена передбачає, що хост Gateway є довіреним; задайте `false`, щоб усюди використовувати автентифікацію зі спільним секретом. - Автентифікація **довіреного проксі** за замовчуванням очікує проксі з урахуванням ідентичності, прив’язаний не до local loopback. Зворотні проксі на тому самому хості через local loopback потребують явного налаштування `gateway.auth.trustedProxy.allowLoopback = true`. - Ставтеся до керування через браузер як до операторського доступу: лише через tailnet і з навмисним сполученням вузлів. Докладніше: [Безпека](/uk/gateway/security). ### macOS: постійний тунель SSH через LaunchAgent Для клієнтів macOS найпростіша постійна конфігурація використовує запис SSH `LocalForward` разом із LaunchAgent, який підтримує тунель активним після перезавантажень і аварійних завершень. #### Крок 1: додайте конфігурацію SSH Відредагуйте `~/.ssh/config`: ```ssh Host remote-gateway HostName User LocalForward 18789 127.0.0.1:18789 IdentityFile ~/.ssh/id_rsa ``` Замініть `` і `` своїми значеннями. #### Крок 2: скопіюйте ключ SSH (одноразово) ```bash ssh-copy-id -i ~/.ssh/id_rsa @ ``` #### Крок 3: налаштуйте токен Gateway ```bash openclaw config set gateway.remote.token "" ``` Натомість використовуйте `gateway.remote.password`, якщо віддалений Gateway використовує автентифікацію за паролем. `OPENCLAW_GATEWAY_TOKEN` залишається чинним перевизначенням на рівні оболонки, але для постійної конфігурації віддаленого клієнта слід використовувати `gateway.remote.token` / `gateway.remote.password`. #### Крок 4: створіть LaunchAgent Збережіть як `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`: ```xml Label ai.openclaw.ssh-tunnel ProgramArguments /usr/bin/ssh -N remote-gateway KeepAlive RunAtLoad ``` #### Крок 5: завантажте LaunchAgent ```bash launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist ``` Тунель автоматично запускається під час входу, перезапускається після аварійного завершення та підтримує перенаправлений порт активним. Якщо у вас залишився LaunchAgent `com.openclaw.ssh-tunnel` від старішої конфігурації, вивантажте та видаліть його. #### Усунення несправностей ```bash # Перевірте, чи працює тунель ps aux | grep "ssh -N remote-gateway" | grep -v grep lsof -i :18789 # Перезапустіть тунель launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Зупиніть тунель launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel ``` | Запис конфігурації | Що він робить | | ------------------------------------ | ----------------------------------------------------------------------- | | `LocalForward 18789 127.0.0.1:18789` | Перенаправляє локальний порт 18789 на віддалений порт 18789 | | `ssh -N` | SSH без виконання віддалених команд (лише перенаправлення портів) | | `KeepAlive` | Автоматично перезапускає тунель після аварійного завершення | | `RunAtLoad` | Запускає тунель під час завантаження LaunchAgent при вході | ## Пов’язані матеріали - [Tailscale](/uk/gateway/tailscale) - [Автентифікація](/uk/gateway/authentication) - [Налаштування віддаленого Gateway](/uk/gateway/remote-gateway-readme)