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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​

Основна ідея

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

​

Поширені налаштування VPN і tailnet

​

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

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

​

Домашній десктоп запускає Gateway

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

​

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

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

​

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

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

• Nodes не запускають сервіс gateway. На одному хості має працювати лише один gateway, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. Кілька gateway).
• “node mode” застосунку macOS — це просто клієнт node через WebSocket Gateway.

​

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) завжди мають пріоритет на шляхах call, які приймають явну автентифікацію.
• Безпека перевизначення URL:
  • Перевизначення URL у CLI (--url) ніколи не використовують неявні облікові дані з конфігурації/env.
  • Перевизначення URL через env (OPENCLAW_GATEWAY_URL) можуть використовувати лише облікові дані env (OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).
• Значення за замовчуванням у локальному режимі:
  • token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token (віддалений резервний варіант застосовується лише коли локальний ввід auth token не задано)
  • password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password (віддалений резервний варіант застосовується лише коли локальний ввід auth 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 ігноруються.
• Перевірки token для віддалених probe/status за замовчуванням суворі: вони використовують лише gateway.remote.token (без резервного переходу на локальний token) під час роботи з віддаленим режимом.
• Перевизначення env для Gateway використовують лише OPENCLAW_GATEWAY_*.

​

Chat UI через SSH

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

​

Remote over SSH у застосунку macOS

​

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

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

​

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

​

Пов’язане

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