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

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

​

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

​

Варианты топологии

​

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

1. Сообщение Telegram поступает в Gateway.
2. Gateway запускает агента, который решает, нужно ли вызывать инструмент узла.
3. Gateway вызывает узел через WebSocket Gateway (node.invoke RPC).
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)

• Loopback + SSH/Tailscale Serve — самый безопасный вариант по умолчанию (без публичного доступа).
• Незашифрованный ws:// разрешён для loopback, частных/LAN-адресов (RFC 1918), link-local, CGNAT, хостов .local и .ts.net. Публичные удалённые хосты должны использовать wss://.
• Привязки не к loopback (lan/tailnet/custom или auto, когда 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, чтобы везде использовать аутентификацию с общим секретом.
• Аутентификация через доверенный прокси по умолчанию предполагает прокси с поддержкой идентификации, привязанный не к loopback. Для обратных прокси на том же хосте через 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