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

OpenClaw запускает один Gateway (главный) на хосте и подключает к нему каждый клиент. Gateway управляет сеансами, профилями аутентификации, каналами и состоянием; всё остальное является клиентом.

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

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

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

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

Для конфигураций с постоянно работающим Gateway и ноутбуком рекомендуется сохранять gateway.bind: "loopback" и использовать Tailscale Serve для интерфейса управления либо доверенную привязку LAN/Tailnet с gateway.remote.transport: "direct". Туннель SSH — резервный вариант, работающий с любой машины.

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

Один Gateway управляет состоянием и каналами; узлы являются периферийными устройствами. Пример (сообщение Telegram направляется инструменту узла):

1. Сообщение Telegram поступает в Gateway.
2. Gateway запускает агента, который решает, нужно ли вызывать инструмент узла.
3. Gateway вызывает узел через WebSocket Gateway (node.invoke RPC).
4. Узел возвращает результат; Gateway отвечает в Telegram.

Узлы не запускают службу Gateway. На каждом хосте должен работать только один Gateway, если только вы намеренно не используете изолированные профили (см. Несколько Gateway). «Режим узла» приложения macOS — это всего лишь клиент узла, работающий через WebSocket Gateway.

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

ssh -N -L 18789:127.0.0.1:18789 user@gateway-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 по умолчанию

Сохраните удалённую цель, чтобы команды CLI использовали её по умолчанию:

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

Если Gateway доступен только через loopback, оставьте URL равным ws://127.0.0.1:18789 и сначала откройте туннель SSH. При использовании транспорта с туннелем SSH в приложении macOS обнаруженное имя хоста Gateway указывается в gateway.remote.sshTarget (user@host или user@host:port); gateway.remote.url остаётся URL локального туннеля. Если удалённый порт отличается от локального, задайте gateway.remote.remotePort.

По умолчанию проверка ключа хоста выполняется строго (gateway.remote.sshHostKeyPolicy: "strict"). Задайте значение "openssh", чтобы вместо этого использовать действующую конфигурацию OpenSSH; перед включением проверьте пользовательские и системные настройки SSH.

Для Gateway, уже доступного в доверенной LAN или Tailnet, используйте прямой режим:

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

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

Определение учётных данных Gateway следует единому контракту для путей вызова, проверки и состояния, а также мониторинга подтверждений выполнения в Discord. Хост узла использует тот же контракт с одним исключением для локального режима (он игнорирует gateway.remote.*).

• Явные учётные данные (--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_*.

Удалённый доступ к интерфейсу чата

У WebChat нет отдельного HTTP-порта; интерфейс чата SwiftUI подключается непосредственно к WebSocket Gateway.

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

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

Приложение строки меню macOS управляет всей конфигурацией целиком: удалёнными проверками состояния, WebChat и перенаправлением голосовой активации. Инструкция: удалённый доступ в macOS.

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

Оставляйте Gateway привязанным только к loopback, если не уверены, что требуется другая привязка.

• 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

Для клиентов macOS проще всего организовать постоянное подключение с помощью записи конфигурации SSH LocalForward и LaunchAgent, который поддерживает туннель после перезагрузок и сбоев.

Шаг 1: добавьте конфигурацию SSH

Измените ~/.ssh/config:

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

Замените <REMOTE_IP> и <REMOTE_USER> своими значениями.

Шаг 2: скопируйте ключ SSH (однократно)

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

Шаг 3: настройте токен Gateway

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

Если удалённый Gateway использует аутентификацию по паролю, вместо этого используйте gateway.remote.password. OPENCLAW_GATEWAY_TOKEN по-прежнему допустим как переопределение на уровне оболочки, но для постоянной настройки удалённого клиента следует использовать gateway.remote.token / gateway.remote.password.

Шаг 4: создайте LaunchAgent

Сохраните как ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist:

<?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 greplsof -i :18789 # Перезапустить туннельlaunchctl kickstart -k gui/$UID/ai.openclaw.ssh-tunnel # Остановить туннельlaunchctl bootout gui/$UID/ai.openclaw.ssh-tunnel

Связанные материалы

• Tailscale
• Аутентификация
• Настройка удалённого Gateway