Перейти к основному содержанию

​
Удалённый доступ (SSH, туннели и tailnet-сети)

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

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

  • WebSocket Gateway привязывается к loopback на настроенном порту (по умолчанию 18789).
  • Для удалённого использования этот loopback‑порт пробрасывается через SSH (или используется tailnet/VPN, что уменьшает потребность в туннелях).

​
Распространённые VPN/tailnet‑сценарии (где живёт агент)

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

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

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

​
2. Домашний десктоп запускает Gateway, ноутбук — удалённое управление

Ноутбук не запускает агент. Он подключается удалённо:
  • Используйте режим Remote over SSH приложения для macOS (Settings → General → «OpenClaw runs»).
  • Приложение открывает и управляет туннелем, поэтому WebChat и проверки состояния «просто работают».
Инструкция: Удалённый доступ к macOS.

​
3. Ноутбук запускает Gateway, удалённый доступ с других машин

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

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

Один сервис gateway владеет состоянием и каналами. Узлы — это периферия. Пример потока (Telegram → узел):
  • Сообщение Telegram поступает в Gateway.
  • Gateway запускает агент и решает, вызывать ли инструмент узла.
  • Gateway вызывает узел через WebSocket Gateway (RPC node.*).
  • Узел возвращает результат; Gateway отправляет ответ обратно в Telegram.
Примечания:
  • Узлы не запускают сервис gateway. На хосте должен работать только один gateway, если только вы намеренно не запускаете изолированные профили (см. Multiple gateways).
  • «Режим узла» приложения для macOS — это просто клиент узла поверх WebSocket Gateway.

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

Создайте локальный туннель к удалённому WS Gateway: 
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,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",
    },
  },
}
Когда gateway доступен только по loopback, оставьте URL равным ws://127.0.0.1:18789 и сначала откройте SSH-туннель.

​
Chat UI через SSH

WebChat больше не использует отдельный HTTP‑порт. UI чата на SwiftUI подключается напрямую к WebSocket Gateway.
  • Пробросьте 18789 через SSH (см. выше), затем подключайте клиентов к ws://127.0.0.1:18789.
  • На macOS предпочтительнее режим «Remote over SSH» приложения, который автоматически управляет туннелем.

​
Приложение для macOS «Remote over SSH»

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

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

Кратко: держите Gateway доступным только по loopback, если вы не уверены, что нужен иной bind.
  • Loopback + SSH/Tailscale Serve — самый безопасный вариант по умолчанию (без публичной экспозиции).
  • Привязки не к loopback (lan/tailnet/custom или auto, когда loopback недоступен) должны использовать токены аутентификации/пароли.
  • gateway.remote.token предназначен только для удалённых вызовов CLI — он не включает локальную аутентификацию.
  • gateway.remote.tlsFingerprint закрепляет удалённый TLS‑сертификат при использовании wss://.
  • Tailscale Serve может аутентифицировать через identity‑заголовки, когда gateway.auth.allowTailscale: true. Установите значение false, если вместо этого нужны токены/пароли.
  • Относитесь к управлению через браузер как к доступу оператора: только tailnet + осознанное сопряжение узлов.
Подробно: Security.