​

Віддалений доступ (SSH, тунелі та tailnet)

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

​

Основна ідея

• Gateway WebSocket прив’язується до loopback на налаштованому порту (типово 18789).
• Для віддаленого використання ви пересилаєте цей loopback-порт через SSH (або використовуєте tailnet/VPN і менше покладаєтеся на тунелі).

​

Типові конфігурації VPN/tailnet (де живе агент)

​

1) Завжди увімкнений Gateway у вашому tailnet (VPS або домашній сервер)

• Найкращий UX: залиште gateway.bind: "loopback" і використовуйте Tailscale Serve для Control UI.
• Резервний варіант: залиште loopback + SSH-тунель з будь-якої машини, якій потрібен доступ.
• Приклади: exe.dev (простий VM) або Hetzner (production VPS).

​

2) Домашній desktop запускає Gateway, laptop є віддаленим керуванням

• Використовуйте режим застосунку macOS Remote over SSH (Settings → General → “OpenClaw runs”).
• Застосунок відкриває й керує тунелем, тож WebChat + перевірки стану «просто працюють».

​

3) Laptop запускає Gateway, віддалений доступ з інших машин

• SSH-тунель до laptop з інших машин, або
• Tailscale Serve для Control UI і loopback-only для Gateway.

​

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

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

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

​

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

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

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:18789",
      token: "your-token",
    },
  },
}

​

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

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

​

Chat UI через SSH

• Переспрямуйте 18789 через SSH (див. вище), а потім підключайте клієнтів до ws://127.0.0.1:18789.
• На macOS віддавайте перевагу режиму застосунку “Remote over SSH”, який автоматично керує тунелем.

​

Застосунок macOS “Remote over SSH”

​

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

• Loopback + SSH/Tailscale Serve — найбезпечніший типовий варіант (без публічного доступу).
• Простий ws:// типово призначений лише для loopback. Для довірених приватних мереж задайте OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 у процесі клієнта як аварійний варіант.
• Прив’язки не до loopback (lan/tailnet/custom або auto, коли loopback недоступний) мають використовувати auth gateway: token, password або reverse proxy з підтримкою ідентичності через gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password — це джерела облікових даних клієнта. Вони самі по собі не налаштовують server auth.
• Локальні шляхи call можуть використовувати gateway.remote.* як резервний варіант лише тоді, коли gateway.auth.* не задано.
• Якщо gateway.auth.token / gateway.auth.password явно налаштовано через SecretRef і вони не розв’язуються, розв’язання завершується із закритою відмовою (без приховування через remote fallback).
• gateway.remote.tlsFingerprint фіксує сертифікат TLS remote при використанні wss://.
• Tailscale Serve може автентифікувати трафік Control UI/WebSocket через заголовки ідентичності, коли gateway.auth.allowTailscale: true; HTTP API endpoints не використовують цю auth через заголовки Tailscale, а натомість дотримуються звичайного HTTP режиму auth gateway. Цей безтокеновий потік припускає, що хост gateway є довіреним. Задайте це значення як false, якщо хочете використовувати auth зі спільним секретом усюди.
• Auth через trusted-proxy призначено лише для конфігурацій з proxy поза loopback і з підтримкою ідентичності. Reverse proxy на loopback на тому самому хості не задовольняють gateway.auth.mode: "trusted-proxy".
• Розглядайте браузерне керування як операторський доступ: лише tailnet + навмисне pairing вузлів.

​

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

​

Крок 1: додайте SSH config

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

​

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

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

​

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

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

​

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

<?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 grep
lsof -i :18789

launchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel

launchctl bootout gui/$UID/ai.openclaw.ssh-tunnel