Настройка удаленного доступа к шлюзу OpenClaw через SSH и VPN

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

Этот репозиторий поддерживает «удаленный доступ по SSH», поддерживая работу одного Шлюза (мастера) на выделенном хосте (десктоп/сервер) и подключая к нему клиентов.

Для операторов (вы / приложение macOS): SSH-туннелирование является универсальным запасным вариантом.
Для узлов (iOS/Android и будущих устройств): подключитесь к WebSocket Шлюза (локальная сеть/tailnet или SSH-туннель по необходимости).

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

WebSocket Шлюза привязывается к loopback-интерфейсу на настроенном вами порту (по умолчанию 18789).
Для удаленного использования вы пробрасываете этот loopback-порт через SSH (или используете tailnet/VPN и меньше туннелирования).

Типичные настройки VPN/tailnet (где живет агент)

Думайте о хосте Шлюза как о «месте, где живет агент». Он владеет сессиями, профилями аутентификации, каналами и состоянием. Ваш ноутбук/десктоп (и узлы) подключаются к этому хосту.

1) Постоянно работающий Шлюз в вашем tailnet (VPS или домашний сервер)

Запустите Шлюз на постоянном хосте и получайте к нему доступ через Tailscale или SSH.

Лучший UX: оставьте gateway.bind: "loopback" и используйте Tailscale Serve для UI управления.
Запасной вариант: оставьте loopback + SSH-туннель с любой машины, которой нужен доступ.
Примеры: exe.dev (простая VM) или Hetzner (продакшен VPS).

Это идеально, когда ваш ноутбук часто спит, но вы хотите, чтобы агент был всегда доступен.

2) Домашний десктоп запускает Шлюз, ноутбук — удаленное управление

Ноутбук не запускает агента. Он подключается удаленно:

Используйте режим Удаленный доступ по SSH в приложении macOS (Настройки → Основные → «OpenClaw запущен»).
Приложение открывает и управляет туннелем, поэтому WebChat и проверки состояния «просто работают».

Инструкция: Удаленный доступ для macOS.

3) Ноутбук запускает Шлюз, удаленный доступ с других машин

Держите Шлюз локально, но безопасно откройте его:

SSH-туннель к ноутбуку с других машин, или
Tailscale Serve для UI управления и оставьте Шлюз только на loopback-интерфейсе.

Руководство: Tailscale и Обзор Web.

Поток команд (что где запускается)

Одна служба шлюза владеет состоянием и каналами. Узлы — это периферийные устройства. Пример потока (Telegram → узел):

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

Примечания:

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

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

Создайте локальный туннель к удаленному WebSocket Шлюза:

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

При активном туннеле:

openclaw health и openclaw status --deep теперь обращаются к удаленному шлюзу через ws://127.0.0.1:18789.
openclaw gateway {status,health,send,agent,call} также могут указывать на переадресованный URL через --url при необходимости.

Примечание: замените 18789 на ваш настроенный gateway.port (или --port/OPENCLAW_GATEWAY_PORT). Примечание: когда вы передаете --url, CLI не возвращается к учетным данным из конфигурации или переменных окружения. Указывайте --token или --password явно. Отсутствие явных учетных данных является ошибкой.

Удаленные значения по умолчанию для CLI

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

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

Когда шлюз работает только на loopback-интерфейсе, оставьте URL как ws://127.0.0.1:18789 и сначала откройте SSH-туннель.

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

Разрешение учетных данных для вызовов/проверок шлюза теперь следует единому общему контракту:

Явные учетные данные (--token, --password или gatewayToken инструмента) всегда имеют приоритет.
Значения по умолчанию для локального режима:
- token: OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token -> gateway.remote.token
- password: OPENCLAW_GATEWAY_PASSWORD -> gateway.auth.password -> gateway.remote.password
Значения по умолчанию для удаленного режима:
- token: gateway.remote.token -> OPENCLAW_GATEWAY_TOKEN -> gateway.auth.token
- password: OPENCLAW_GATEWAY_PASSWORD -> gateway.remote.password -> gateway.auth.password
Проверки токена для удаленных проверок/статуса строги по умолчанию: они используют только gateway.remote.token (без возврата к локальному токену) при нацеливании на удаленный режим.
Устаревшие переменные окружения CLAWDBOT_GATEWAY_* используются только совместимыми путями вызовов; разрешение для проверок/статуса/аутентификации использует только OPENCLAW_GATEWAY_*.

Интерфейс чата через SSH

WebChat больше не использует отдельный HTTP-порт. UI чата SwiftUI подключается напрямую к WebSocket Шлюза.

Пробросьте 18789 через SSH (см. выше), затем подключите клиенты к ws://127.0.0.1:18789.
На macOS предпочтительнее использовать режим «Удаленный доступ по SSH» в приложении, который автоматически управляет туннелем.

Приложение macOS «Удаленный доступ по SSH»

Приложение в строке меню macOS может управлять той же настройкой от начала до конца (удаленные проверки состояния, WebChat и переадресация Voice Wake). Инструкция: Удаленный доступ для macOS.

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

Короткая версия: оставляйте Шлюз только на loopback-интерфейсе, если вы не уверены, что нужна привязка.

Loopback + SSH/Tailscale Serve — самое безопасное значение по умолчанию (нет публичного доступа).
Обычный ws:// по умолчанию работает только на loopback-интерфейсе. Для доверенных частных сетей установите OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 в клиентском процессе как аварийный вариант.
Привязки не к loopback-интерфейсу (lan/tailnet/custom, или auto, когда loopback недоступен) должны использовать токены/пароли аутентификации.
gateway.remote.token / .password являются источниками учетных данных клиента. Они не настраивают аутентификацию сервера сами по себе.
Локальные пути вызовов могут использовать gateway.remote.* как запасной вариант, когда gateway.auth.* не установлен.
gateway.remote.tlsFingerprint фиксирует удаленный TLS-сертификат при использовании wss://.
Tailscale Serve может аутентифицировать трафик UI управления/WebSocket через заголовки идентификации, когда gateway.auth.allowTailscale: true; конечные точки HTTP API по-прежнему требуют аутентификации по токену/паролю. Этот поток без токена предполагает, что хост шлюза доверенный. Установите значение false, если вы хотите токены/пароли везде.
Относитесь к управлению через браузер как к доступу оператора: только tailnet + преднамеренное сопряжение узлов.

Подробнее: Безопасность.

Обнаружение Bonjour Настройка удаленного шлюза