--- read_when: - Запуск или устранение неполадок в конфигурациях удалённого Gateway summary: Удалённый доступ с помощью Gateway WS, SSH-туннелей и tailnet-сетей title: Удалённый доступ x-i18n: generated_at: "2026-07-13T19:49:36Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 78daaad7bcb9f80072eaa2d6946bff9f28ba1ec4f95a68edb0d24cf7f9c3fec2 source_path: gateway/remote.md workflow: 16 --- 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 в tailnet | Постоянный хост (VPS или домашний сервер), доступный через Tailscale или SSH | Ноутбуков, которые часто переходят в спящий режим, но требуют постоянной работы агента. См. [exe.dev](/ru/install/exe-dev) (простая ВМ) или [Hetzner](/ru/install/hetzner) (рабочий VPS). | | Домашний настольный компьютер | Настольный компьютер; ноутбук подключается удалённо через удалённый режим приложения macOS (Settings → Connection → OpenClaw runs) | Размещения агента на постоянно включённом оборудовании. Инструкция: [удалённый доступ в macOS](/ru/platforms/mac/remote). | | Ноутбук | Ноутбук с безопасно открытым доступом через туннель SSH или Tailscale Serve (сохраняйте `gateway.bind: "loopback"`) | Конфигураций с одной машиной. См. [Tailscale](/ru/gateway/tailscale) и [веб-интерфейс](/ru/web). | Для конфигураций с постоянно работающим 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](/ru/gateway/multiple-gateways)). «Режим узла» приложения macOS — это всего лишь клиент узла, работающий через WebSocket Gateway. ## Туннель SSH (CLI и инструменты) ```bash 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`. Замените `18789` настроенным значением `gateway.port` (или `--port` / `OPENCLAW_GATEWAY_PORT`). `--url` никогда не использует учётные данные из конфигурации или переменных окружения в качестве резервного варианта. Явно передайте `--token` или `--password`; без них клиент не отправляет учётные данные, и подключение завершается ошибкой, если целевой Gateway требует аутентификацию. ## Удалённые настройки CLI по умолчанию Сохраните удалённую цель, чтобы команды CLI использовали её по умолчанию: ```json5 { 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, используйте прямой режим: ```json5 { 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](/ru/platforms/mac/remote). ## Правила безопасности (удалённый доступ/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 и с осознанным сопряжением узлов. Подробнее: [Безопасность](/ru/gateway/security). ### macOS: постоянный туннель SSH через LaunchAgent Для клиентов macOS проще всего организовать постоянное подключение с помощью записи конфигурации SSH `LocalForward` и LaunchAgent, который поддерживает туннель после перезагрузок и сбоев. #### Шаг 1: добавьте конфигурацию SSH Измените `~/.ssh/config`: ```ssh Host remote-gateway HostName User LocalForward 18789 127.0.0.1:18789 IdentityFile ~/.ssh/id_rsa ``` Замените `` и `` своими значениями. #### Шаг 2: скопируйте ключ SSH (однократно) ```bash ssh-copy-id -i ~/.ssh/id_rsa @ ``` #### Шаг 3: настройте токен Gateway ```bash openclaw config set gateway.remote.token "" ``` Если удалённый Gateway использует аутентификацию по паролю, вместо этого используйте `gateway.remote.password`. `OPENCLAW_GATEWAY_TOKEN` по-прежнему допустим как переопределение на уровне оболочки, но для постоянной настройки удалённого клиента следует использовать `gateway.remote.token` / `gateway.remote.password`. #### Шаг 4: создайте LaunchAgent Сохраните как `~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist`: ```xml Label ai.openclaw.ssh-tunnel ProgramArguments /usr/bin/ssh -N remote-gateway KeepAlive RunAtLoad ``` #### Шаг 5: загрузите LaunchAgent ```bash launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist ``` Туннель автоматически запускается при входе в систему, перезапускается после сбоя и поддерживает перенаправленный порт активным. Если у вас остался LaunchAgent `com.openclaw.ssh-tunnel` от старой конфигурации, выгрузите и удалите его. #### Устранение неполадок ```bash # Проверить, работает ли туннель 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 ``` | Запись конфигурации | Что она делает | | ---------------------------------- | -------------------------------------------------------------------- | | `LocalForward 18789 127.0.0.1:18789` | Перенаправляет локальный порт 18789 на удалённый порт 18789 | | `ssh -N` | SSH без выполнения удалённых команд (только перенаправление портов) | | `KeepAlive` | Автоматически перезапускает туннель после сбоя | | `RunAtLoad` | Запускает туннель при загрузке LaunchAgent во время входа в систему | ## Связанные материалы - [Tailscale](/ru/gateway/tailscale) - [Аутентификация](/ru/gateway/authentication) - [Настройка удалённого Gateway](/ru/gateway/remote-gateway-readme)