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