--- read_when: - Запуск хоста Node без графического интерфейса - Сопряжение узла не на macOS для system.run summary: Справочник CLI для `openclaw node` (хост Node без графического интерфейса) title: Node x-i18n: generated_at: "2026-07-16T16:43:45Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: d17b96b8829bef4202ff220d9b20e04c183702f997f669120cb16aa7191235b6 source_path: cli/node.md workflow: 16 --- # `openclaw node` Запустите **безголовый хост Node**, который подключается к WebSocket Gateway и предоставляет `system.run` / `system.which` на этом компьютере. В macOS приложение в строке меню уже встраивает эту среду выполнения хоста Node в собственное подключение Node и добавляет нативные возможности Mac. Используйте `openclaw node run` на Mac, только если вам намеренно нужен безголовый Node без приложения. Одновременный запуск обоих вариантов создаёт две идентичности Node для одного компьютера. ## Зачем использовать хост Node? Используйте хост Node, если требуется, чтобы агенты **выполняли команды на других компьютерах** в вашей сети без установки на них полноценного вспомогательного приложения для macOS. Типичные сценарии использования: - Выполнение команд на удалённых компьютерах Linux/Windows (серверах сборки, лабораторных машинах, NAS). - Сохранение **изолированного** выполнения на Gateway с делегированием одобренных запусков другим хостам. - Предоставление облегчённой безголовой цели выполнения для автоматизации или узлов CI. Выполнение по-прежнему контролируется **одобрениями exec** и списками разрешений для каждого агента на хосте Node, поэтому доступ к командам можно сделать ограниченным и явным. После подключения `openclaw node run` может публиковать инструменты на базе плагинов или MCP. По умолчанию Gateway доверяет дескрипторам от сопряжённого Node, но требует, чтобы команда каждого дескриптора оставалась в пределах одобренной поверхности команд Node. Агент видит каждый принятый дескриптор как обычный инструмент плагина, но выполнение по-прежнему проходит через `node.invoke`, поэтому отключение Node удаляет инструмент из новых запусков агента. Операторы Gateway могут отключить публикацию с помощью `gateway.nodes.pluginTools.enabled: false`. Для декларативных инструментов MCP добавьте обычную конфигурацию сервера MCP в `nodeHost.mcp.servers` в `openclaw.json` на компьютере Node, затем перезапустите хост Node. Node объявляет защищённое одобрениями семейство команд `mcp.tools.call.v1` и после подключения публикует перечисленные инструменты; последующее изменение списка серверов не требует повторного сопряжения. См. [Серверы MCP на хосте Node](/ru/nodes#node-hosted-mcp-servers). ## Прокси браузера (без настройки) Хосты Node автоматически объявляют прокси браузера, если `browser.enabled` не отключён на Node. Это позволяет агенту использовать автоматизацию браузера на этом Node без дополнительной настройки. По умолчанию прокси предоставляет обычную поверхность профилей браузера Node. Если задать `nodeHost.browserProxy.allowProfiles`, прокси перейдёт в ограничительный режим: обращение к профилям вне списка разрешений будет отклоняться, а маршруты создания и удаления постоянных профилей через прокси будут заблокированы. При необходимости отключите его на Node: ```json5 { nodeHost: { browserProxy: { enabled: false, }, }, } ``` ## Запуск (на переднем плане) ```bash openclaw node run --host --port 18789 ``` Параметры: - `--host `: хост WebSocket Gateway (по умолчанию: `127.0.0.1`) - `--port `: порт WebSocket Gateway (по умолчанию: `18789`) - `--context-path `: путь контекста WebSocket Gateway (например, `/openclaw-gw`). Добавляется к URL WebSocket. - `--tls`: использовать TLS для подключения к Gateway - `--no-tls`: принудительно использовать незашифрованное подключение к Gateway, даже если локальная конфигурация Gateway включает TLS - `--tls-fingerprint `: ожидаемый отпечаток сертификата TLS (sha256) - `--node-id `: переопределить идентификатор экземпляра клиента, хранящийся в общем состоянии SQLite (не сбрасывает сопряжение) - `--display-name `: переопределить отображаемое имя Node ## Аутентификация Gateway для хоста Node `openclaw node run` и `openclaw node install` получают данные аутентификации Gateway из конфигурации или переменных окружения (в командах Node нет флагов `--token`/`--password`): - Сначала проверяются `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`. - Затем используется резервный вариант из локальной конфигурации: `gateway.auth.token` / `gateway.auth.password`. - В локальном режиме хост Node намеренно не наследует `gateway.remote.token` / `gateway.remote.password`. - Если `gateway.auth.token` / `gateway.auth.password` явно настроен через SecretRef и не разрешён, получение данных аутентификации Node завершается с запретом по умолчанию (без маскировки удалённым резервным вариантом). - В `gateway.mode=remote` поля удалённого клиента (`gateway.remote.token` / `gateway.remote.password`) также могут использоваться согласно правилам приоритета удалённых источников. - Получение данных аутентификации хоста Node учитывает только переменные окружения `OPENCLAW_GATEWAY_*`. Для Node, подключающегося к незашифрованному Gateway `ws://`, допустимы loopback-адреса, литералы частных IP-адресов, хосты `.local` и Tailnet `*.ts.net`. Для других доверенных имён частного DNS задайте `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`; без этого запуск Node завершится с запретом по умолчанию и предложит использовать `wss://`, туннель SSH или Tailscale. Это явное согласие через окружение процесса, а не ключ конфигурации `openclaw.json`. `openclaw node install` сохраняет его в управляемой службе Node, если оно присутствует в окружении команды установки. ## Служба (в фоновом режиме) Установите безголовый хост Node как пользовательскую службу (launchd в macOS, systemd в Linux, планировщик заданий Windows в Windows). ```bash openclaw node install --host --port 18789 ``` Параметры: - `--host `: хост WebSocket Gateway (по умолчанию: `127.0.0.1`) - `--port `: порт WebSocket Gateway (по умолчанию: `18789`) - `--context-path `: путь контекста WebSocket Gateway (например, `/openclaw-gw`). Добавляется к URL WebSocket. - `--tls`: использовать TLS для подключения к Gateway - `--tls-fingerprint `: ожидаемый отпечаток сертификата TLS (sha256) - `--node-id `: переопределить идентификатор экземпляра клиента, хранящийся в общем состоянии SQLite (не сбрасывает сопряжение) - `--display-name `: переопределить отображаемое имя Node - `--runtime `: среда выполнения службы (`node`) - `--force`: переустановить или перезаписать, если уже установлено Управление службой: ```bash openclaw node status openclaw node start openclaw node stop openclaw node restart openclaw node uninstall ``` Используйте `openclaw node run` для запуска хоста Node на переднем плане (без службы). Команды службы принимают `--json` для вывода в машиночитаемом формате. Хост Node повторно подключается после перезапуска Gateway и закрытия сетевого соединения в рамках процесса. Если Gateway сообщает о терминальной приостановке аутентификации по токену, паролю или начальной настройке, хост Node записывает сведения о закрытии в журнал и завершается с ненулевым кодом, чтобы launchd/systemd/планировщик заданий мог перезапустить его со свежей конфигурацией и учётными данными. Приостановки из-за необходимости сопряжения остаются в потоке на переднем плане, чтобы ожидающий запрос можно было одобрить. ## Сопряжение При первом подключении на Gateway создаётся ожидающий запрос на сопряжение устройства (`role: node`). Если хост Gateway может подключиться к хосту Node по SSH без взаимодействия с пользователем (тот же пользователь, доверенный ключ хоста), ожидающий запрос одобряется автоматически: Gateway запускает `openclaw node identity --json` на хосте Node через SSH и одобряет запрос при точном совпадении ключа устройства. По умолчанию это включено; требования и способ отключения (`gateway.nodes.pairing.sshVerify: false`) см. в разделе [Автоматическое одобрение устройства с проверкой по SSH](/ru/gateway/pairing#ssh-verified-device-auto-approval-default). В противном случае одобрите вручную: ```bash openclaw devices list openclaw devices approve ``` Проверьте локальную идентичность Node, с которой сверяется Gateway: ```bash openclaw node identity --json ``` Команда выводит идентификатор устройства и открытый ключ из `identity/device.json` и никогда не создаёт и не изменяет файлы идентичности. В строго контролируемых сетях Node оператор Gateway может явно включить автоматическое одобрение первого сопряжения Node из доверенных CIDR: ```json5 { gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24"], }, }, }, } ``` По умолчанию это отключено (`autoApproveCidrs` не задан). Это применяется только к новому сопряжению `role: node` без запрошенных областей доступа с IP-адреса клиента, которому доверяет Gateway. Клиенты оператора и браузера, Control UI, WebChat, а также обновления роли, областей доступа, метаданных или открытого ключа по-прежнему требуют ручного одобрения. Если Node повторяет сопряжение с изменёнными данными аутентификации (ролью, областями доступа или открытым ключом), предыдущий ожидающий запрос заменяется и создаётся новый `requestId`. Перед одобрением снова выполните `openclaw devices list`. ### Состояние идентичности и сопряжения Безголовый Node отделяет идентификатор экземпляра клиента от подписанной идентичности устройства, которую Gateway использует для сопряжения и маршрутизации. Это состояние хранится в каталоге состояния OpenClaw (`~/.openclaw` по умолчанию или `$OPENCLAW_STATE_DIR`, если задано): | Состояние | Назначение | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `state/openclaw.sqlite` (`node_host_config`) | Идентификатор экземпляра клиента, отображаемое имя и метаданные подключения к Gateway. Клиент отправляет этот идентификатор как `instanceId`. | | `identity/device.json` | Подписанная пара ключей Ed25519 и производный идентификатор устройства. Для подписанных подключений этот идентификатор устройства служит маршрутизируемым идентификатором Node и идентичностью сопряжения. | | `identity/device-auth.json` | Токены сопряжённых устройств с ключами по криптографическому идентификатору устройства и роли. | `--node-id` изменяет только идентификатор экземпляра клиента в общем состоянии SQLite. Он не изменяет криптографический идентификатор устройства и не очищает данные аутентификации сопряжения. Перенос устаревшего `node.json` с помощью `openclaw doctor --fix` также не сбрасывает сопряжение. Чтобы отозвать и повторно сопрячь Node: 1. На Gateway выполните `openclaw nodes remove --node `. 2. На Node перезапустите установленную службу с помощью `openclaw node restart` либо остановите и повторно выполните команду переднего плана `openclaw node run`. Это запустит процесс сопряжения устройства. Если `openclaw devices list` не показывает запрос, а Node сообщает `AUTH_DEVICE_TOKEN_MISMATCH`, перезапустите или повторно запустите его ещё раз. Отклонённая попытка очищает отозванный локальный токен; следующая попытка сможет запросить сопряжение. 3. На Gateway выполните `openclaw devices list`, затем `openclaw devices approve `. 4. Снова перезапустите или повторно запустите Node. Клиент, приостановленный для сопряжения, не возобновляет работу автоматически после одобрения; это повторное подключение создаёт отдельный запрос поверхности команд. 5. На Gateway выполните `openclaw nodes pending`, затем `openclaw nodes approve `. Эти два идентификатора запроса различаются. Применимая политика доверенных CIDR может автоматически одобрить этап первого сопряжения устройства; одобрение поверхности команд остаётся отдельной проверкой. Старые выпуски OpenClaw хранили состояние хоста Node в `node.json` и могли оставлять там устаревшее поле `token`. Остановите хост Node и один раз выполните `openclaw doctor --fix`; Doctor импортирует поддерживаемые поля идентичности и подключения в SQLite, отбрасывает неиспользуемое поле токена, проверяет строку и удаляет устаревший файл. Обычные команды Node завершаются с запретом по умолчанию и этой инструкцией по исправлению, пока файл или прерванная операция Doctor остаются на месте. Сохраняйте конфиденциальность обоих файлов в `identity/`; они содержат пару ключей устройства и токены аутентификации. ## Одобрения exec `system.run` контролируется локальными одобрениями exec: - `$OPENCLAW_STATE_DIR/exec-approvals.json` или `~/.openclaw/exec-approvals.json`, если переменная не задана - [Одобрения exec](/ru/tools/exec-approvals) - `openclaw approvals --node ` (редактируется с Gateway) Для одобренного асинхронного выполнения exec на Node OpenClaw подготавливает канонический `systemRunPlan` до запроса одобрения. Последующая одобренная пересылка `system.run` повторно использует этот сохранённый план, поэтому изменения полей команды, рабочего каталога или сеанса после создания запроса на одобрение отклоняются и не могут изменить то, что выполняет Node. ## См. также - [Справочник CLI](/ru/cli) - [Узлы](/ru/node