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

Цей репозиторій підтримує віддалений доступ до Gateway, утримуючи один Gateway (master), запущений на виділеному хості (настільному комп’ютері/сервері), і підключаючи до нього клієнтів.

• Для операторів (ви / застосунок macOS): прямий WebSocket у LAN/Tailnet найпростіший, коли gateway доступний; тунелювання SSH — універсальний резервний варіант.
• Для вузлів (iOS/Android і майбутні пристрої): підключайтеся до WebSocket Gateway (LAN/tailnet або SSH-тунель за потреби).

Основна ідея

• WebSocket Gateway зазвичай прив’язується до local loopback на налаштованому порту (типово 18789).
• Для віддаленого використання відкрийте його через Tailscale Serve або довірену прив’язку LAN/Tailnet, або переадресуйте порт local loopback через SSH.

Типові налаштування VPN і tailnet

Уявляйте хост Gateway як місце, де живе агент. Він володіє сеансами, профілями автентифікації, каналами та станом. Ваш ноутбук, настільний комп’ютер і вузли підключаються до цього хоста.

Постійно ввімкнений Gateway у вашому tailnet

Запустіть Gateway на постійному хості (VPS або домашньому сервері) і звертайтеся до нього через Tailscale або SSH.

• Найкращий UX: залиште gateway.bind: "loopback" і використовуйте Tailscale Serve для Control UI.
• Довірені LAN/Tailnet: прив’яжіть gateway до приватного інтерфейсу й підключайтеся напряму з gateway.remote.transport: "direct".
• Резервний варіант: залиште local loopback плюс SSH-тунель з будь-якої машини, якій потрібен доступ.
• Приклади: exe.dev (проста VM) або Hetzner (production VPS).

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

Домашній настільний комп’ютер запускає Gateway

Ноутбук не запускає агента. Він підключається віддалено:

• Використовуйте віддалений режим застосунку macOS (Settings → General → OpenClaw runs).
• Застосунок підключається напряму, коли gateway доступний у LAN/Tailnet, або відкриває й керує SSH-тунелем, коли ви вибираєте SSH.

Runbook: віддалений доступ macOS.

Ноутбук запускає Gateway

Залиште Gateway локальним, але безпечно відкрийте доступ до нього:

• SSH-тунель до ноутбука з інших машин, або
• Tailscale Serve для Control UI, залишаючи Gateway доступним лише через local loopback.

Посібники: Tailscale і огляд Web.

Потік команд (що де запускається)

Одна служба gateway володіє станом + каналами. Вузли є периферійними.

Приклад потоку (Telegram → вузол):

• Повідомлення Telegram надходить до Gateway.
• Gateway запускає агента й вирішує, чи викликати інструмент вузла.
• Gateway викликає вузол через WebSocket Gateway (node.* RPC).
• Вузол повертає результат; Gateway відповідає назад у Telegram.

Примітки:

• Вузли не запускають службу gateway. На кожному хості має працювати лише один gateway, якщо ви навмисно не запускаєте ізольовані профілі (див. Кілька gateway).
• «Режим вузла» застосунку macOS — це просто клієнт вузла через WebSocket Gateway.

SSH-тунель (CLI + інструменти)

Створіть локальний тунель до віддаленого Gateway WS:

ssh -N -L 18789:127.0.0.1:18789 user@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; gateway.remote.url залишається локальною URL-адресою тунелю. Якщо ці порти відрізняються, установіть gateway.remote.remotePort як порт gateway на хості SSH. Перевірка ключа хоста типово сувора. Керовані псевдоніми можуть явно використовувати свою ефективну політику довіри OpenSSH за допомогою gateway.remote.sshHostKeyPolicy: "openssh"; перегляньте відповідні користувацькі та системні налаштування SSH, перш ніж увімкнути це.

Для gateway, який уже доступний у довіреній LAN або Tailnet, використовуйте прямий режим:

{  gateway: {    mode: "remote",    remote: {      transport: "direct",      url: "ws://192.168.0.202:18789",      token: "your-token",    },  },}

Пріоритет облікових даних

Визначення облікових даних Gateway дотримується одного спільного контракту для шляхів call/probe/status і моніторингу exec-approval у Discord. Node-host використовує той самий базовий контракт з одним винятком для локального режиму (він навмисно ігнорує gateway.remote.*):

• Явні облікові дані (--token, --password або інструмент gatewayToken) завжди мають пріоритет на шляхах виклику, які приймають явну автентифікацію.
• Безпека перевизначення URL:
  • Перевизначення URL у CLI (--url) ніколи не повторно використовують неявні облікові дані config/env.
  • Перевизначення URL через env (OPENCLAW_GATEWAY_URL) можуть використовувати лише облікові дані env (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Типові значення локального режиму:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (віддалений резервний варіант застосовується лише коли локальне введення токена автентифікації не задано)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (віддалений резервний варіант застосовується лише коли локальне введення пароля автентифікації не задано)
• Типові значення віддаленого режиму:
  • token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
• Виняток локального режиму Node-host: gateway.remote.token / gateway.remote.password ігноруються.
• Перевірки токенів remote probe/status типово суворі: вони використовують лише gateway.remote.token (без локального резервного токена), коли націлюються на віддалений режим.
• Перевизначення env Gateway використовують лише OPENCLAW_GATEWAY_*.

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

WebChat більше не використовує окремий HTTP-порт. SwiftUI Chat UI підключається напряму до WebSocket Gateway.

• Переадресуйте 18789 через SSH (див. вище), потім підключайте клієнтів до ws://127.0.0.1:18789.
• Для прямого режиму LAN/Tailnet підключайте клієнтів до налаштованої приватної URL-адреси ws:// або захищеної wss://.
• На macOS віддавайте перевагу віддаленому режиму застосунку, який автоматично керує вибраним транспортом.

Віддалений режим застосунку macOS

Застосунок рядка меню macOS може керувати тим самим налаштуванням від початку до кінця (віддалені перевірки статусу, WebChat і переадресація Voice Wake).

Runbook: віддалений доступ macOS.

Правила безпеки (remote/VPN)

Коротко: залишайте Gateway доступним лише через local loopback, якщо ви не впевнені, що вам потрібна прив’язка.

• Local loopback + SSH/Tailscale Serve — найбезпечніше типове рішення (без публічного доступу).
• Plaintext ws:// приймається для local loopback, LAN, link-local, .local, .ts.net і хостів Tailscale CGNAT. Публічні віддалені хости мають використовувати wss://.
• Прив’язки поза local loopback (lan/tailnet/custom або auto, коли local loopback недоступний) мають використовувати автентифікацію gateway: токен, пароль або identity-aware reverse proxy з 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. Без налаштованого або раніше збереженого pin macOS закріплює сертифікат першого використання лише після успішної звичайної системної довіри; gateway із самопідписаними сертифікатами або приватним CA, яким macOS ще не довіряє, потребують явного відбитка або Remote over SSH.
• Tailscale Serve може автентифікувати трафік Control UI/WebSocket через identity headers, коли gateway.auth.allowTailscale: true; кінцеві точки HTTP API не використовують цю автентифікацію заголовків Tailscale, а натомість дотримуються звичайного HTTP режиму автентифікації gateway. Цей потік без токена припускає, що хост gateway є довіреним. Установіть його на false, якщо ви хочете автентифікацію зі спільним секретом усюди.
• Автентифікація Trusted-proxy типово очікує налаштування identity-aware proxy поза local loopback. Reverse proxy на тому самому хості через local loopback потребують явного gateway.auth.trustedProxy.allowLoopback = true.
• Ставтеся до керування з браузера як до операторського доступу: лише tailnet + навмисне спарювання вузлів.

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

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

Для клієнтів macOS, що підключаються до віддаленого gateway, найпростіше постійне налаштування використовує запис конфігурації 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>"

Крок 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