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

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

​

Основна ідея

​

Варіанти топології

​

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

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

​

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

ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

​

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

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

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

​

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

• Явні облікові дані (--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_*.

​

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

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

​

Режим віддаленої роботи застосунку macOS

​

Правила безпеки (віддалений доступ/VPN)

• 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

​

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

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: налаштуйте токен 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

​

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

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