> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # Удалённый доступ 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](https://docs2.openclaw.ai/ru/install/exe-dev.md) (простая ВМ) или [Hetzner](https://docs2.openclaw.ai/ru/install/hetzner.md) (рабочий VPS). | | Домашний настольный компьютер | Настольный компьютер; ноутбук подключается удалённо через удалённый режим приложения macOS (Settings → Connection → OpenClaw runs) | Размещения агента на постоянно включённом оборудовании. Инструкция: [удалённый доступ в macOS](https://docs2.openclaw.ai/ru/platforms/mac/remote.md). | | Ноутбук | Ноутбук с безопасно открытым доступом через туннель SSH или Tailscale Serve (сохраняйте `gateway.bind: "loopback"`) | Конфигураций с одной машиной. См. [Tailscale](https://docs2.openclaw.ai/ru/gateway/tailscale.md) и [веб-интерфейс](https://docs2.openclaw.ai/ru/web.md). | Для конфигураций с постоянно работающим 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](https://docs2.openclaw.ai/ru/gateway/multiple-gateways.md)). «Режим узла» приложения macOS — это всего лишь клиент узла, работающий через WebSocket Gateway. ## Туннель SSH (CLI и инструменты) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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`. > [!NOTE] > > Замените `18789` настроенным значением `gateway.port` (или `--port` / `OPENCLAW_GATEWAY_PORT`). > [!WARNING] > > `--url` никогда не использует учётные данные из конфигурации или переменных окружения в качестве резервного варианта. Явно передайте `--token` или `--password`; без них клиент не отправляет учётные данные, и подключение завершается ошибкой, если целевой Gateway требует аутентификацию. ## Удалённые настройки CLI по умолчанию Сохраните удалённую цель, чтобы команды CLI использовали её по умолчанию: ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} { 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](https://docs2.openclaw.ai/ru/platforms/mac/remote.md). ## Правила безопасности (удалённый доступ/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 и с осознанным сопряжением узлов. Подробнее: [Безопасность](https://docs2.openclaw.ai/ru/gateway/security.md). ### macOS: постоянный туннель SSH через LaunchAgent Для клиентов macOS проще всего организовать постоянное подключение с помощью записи конфигурации SSH `LocalForward` и LaunchAgent, который поддерживает туннель после перезагрузок и сбоев. #### Шаг 1: добавьте конфигурацию SSH Измените `~/.ssh/config`: ```ssh theme={"theme":{"light":"min-light","dark":"min-dark"}} Host remote-gateway HostName User LocalForward 18789 127.0.0.1:18789 IdentityFile ~/.ssh/id_rsa ``` Замените `` и `` своими значениями. #### Шаг 2: скопируйте ключ SSH (однократно) ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} ssh-copy-id -i ~/.ssh/id_rsa @ ``` #### Шаг 3: настройте токен Gateway ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 theme={"theme":{"light":"min-light","dark":"min-dark"}} Label ai.openclaw.ssh-tunnel ProgramArguments /usr/bin/ssh -N remote-gateway KeepAlive RunAtLoad ``` #### Шаг 5: загрузите LaunchAgent ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.openclaw.ssh-tunnel.plist ``` Туннель автоматически запускается при входе в систему, перезапускается после сбоя и поддерживает перенаправленный порт активным. > [!NOTE] > > Если у вас остался LaunchAgent `com.openclaw.ssh-tunnel` от старой конфигурации, выгрузите и удалите его. #### Устранение неполадок ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Проверить, работает ли туннель 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](https://docs2.openclaw.ai/ru/gateway/tailscale.md) * [Аутентификация](https://docs2.openclaw.ai/ru/gateway/authentication.md) * [Настройка удалённого Gateway](https://docs2.openclaw.ai/ru/gateway/remote-gateway-readme)