Удаленный доступ

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

​

Основная идея

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

​

Распространенные схемы VPN и tailnet

​

Постоянно включенный Gateway в вашем tailnet

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

​

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

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

​

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

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

​

Поток команд (что где выполняется)

• Сообщение Telegram приходит в Gateway.
• Gateway запускает агент и решает, нужно ли вызвать инструмент узла.
• Gateway вызывает узел через WebSocket Gateway (node.* RPC).
• Узел возвращает результат; Gateway отправляет ответ обратно в Telegram.

• Узлы не запускают службу gateway. На одном хосте должен работать только один gateway, если вы не запускаете изолированные профили намеренно (см. несколько gateway).
• «Режим узла» в приложении macOS — это просто клиент узла поверх 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",
    },
  },
}

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

​

Приоритет учетных данных

• Явные учетные данные (--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 (удаленный резерв применяется только когда локальный входной 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

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

​

Удаленный режим приложения macOS

​

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

• Loopback + SSH/Tailscale Serve — самый безопасный вариант по умолчанию (без публичного доступа).
• Открытый ws:// принимается для loopback, LAN, link-local, .local, .ts.net и хостов Tailscale CGNAT. Публичные удаленные хосты должны использовать wss://.
• Привязки не к loopback (lan/tailnet/custom или auto, когда loopback недоступен) должны использовать auth gateway: token, password или identity-aware reverse proxy с gateway.auth.mode: "trusted-proxy".
• gateway.remote.token / .password являются источниками учетных данных клиента. Сами по себе они не настраивают auth сервера.
• Локальные пути вызова могут использовать gateway.remote.* как резерв только когда gateway.auth.* не задан.
• Если gateway.auth.token / gateway.auth.password явно настроен через SecretRef и не разрешен, разрешение завершается закрыто (без маскировки удаленным резервом).
• gateway.remote.tlsFingerprint закрепляет удаленный TLS-сертификат при использовании wss://, включая прямой режим macOS. Без настроенного или ранее сохраненного закрепления macOS закрепляет сертификат при первом использовании только после прохождения обычной системной проверки доверия; gateway с самоподписанными сертификатами или частным CA, которым macOS еще не доверяет, требуют явный fingerprint или Remote over SSH.
• Tailscale Serve может аутентифицировать трафик Control UI/WebSocket через identity headers, когда gateway.auth.allowTailscale: true; конечные точки HTTP API не используют эту Tailscale header auth и вместо этого следуют обычному HTTP auth-режиму gateway. Этот поток без token предполагает, что хост gateway доверенный. Установите false, если хотите shared-secret auth везде.
• Trusted-proxy auth по умолчанию ожидает настройки non-loopback identity-aware proxy. Same-host loopback reverse proxies требуют явного 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: настройте 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