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

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.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). «Режим вузла» застосунку macOS — це лише клієнт вузла, що працює через WebSocket Gateway.

Тунель SSH (CLI та інструменти)

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.

Стандартні налаштування віддаленого CLI

Збережіть віддалену ціль, щоб команди CLI використовували її за замовчуванням:

{  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, використовуйте прямий режим:

{  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.

Правила безпеки (віддалений доступ/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 і з навмисним сполученням вузлів.

Докладніше: Безпека.

macOS: постійний тунель SSH через LaunchAgent

Для клієнтів macOS найпростіша постійна конфігурація використовує запис SSH LocalForward разом із LaunchAgent, який підтримує тунель активним після перезавантажень і аварійних завершень.

Крок 1: додайте конфігурацію SSH

Відредагуйте ~/.ssh/config:

Host remote-gateway    HostName <REMOTE_IP>    User <REMOTE_USER>    LocalForward 18789 127.0.0.1:18789    IdentityFile ~/.ssh/id_rsa

Замініть <REMOTE_IP> і <REMOTE_USER> своїми значеннями.

Крок 2: скопіюйте ключ SSH (одноразово)

ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>

Крок 3: налаштуйте токен Gateway

openclaw config set gateway.remote.token "<your-token>"

Натомість використовуйте gateway.remote.password, якщо віддалений Gateway використовує автентифікацію за паролем. OPENCLAW_GATEWAY_TOKEN залишається чинним перевизначенням на рівні оболонки, але для постійної конфігурації віддаленого клієнта слід використовувати gateway.remote.token / gateway.remote.password.

Крок 4: створіть LaunchAgent

Збережіть як ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"><plist version="1.0"><dict>    <key>Label</key>    <string>ai.openclaw.ssh-tunnel</string>    <key>ProgramArguments</key>    <array>        <string>/usr/bin/ssh</string>        <string>-N</string>        <string>remote-gateway</string>    </array>    <key>KeepAlive</key>    <true/>    <key>RunAtLoad</key>    <true/></dict></plist>

Крок 5: завантажте LaunchAgent

launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist

Тунель автоматично запускається під час входу, перезапускається після аварійного завершення та підтримує перенаправлений порт активним.

Усунення несправностей

# Перевірте, чи працює тунельps aux | grep "ssh -N remote-gateway" | grep -v greplsof -i :18789 # Перезапустіть тунельlaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Зупиніть тунельlaunchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

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

• Tailscale
• Автентифікація
• Налаштування віддаленого Gateway