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 на хостах узлов.

Прокси браузера (без настройки)

Хосты узлов автоматически объявляют прокси браузера, если browser.enabled не отключён на узле. Благодаря этому агент может использовать автоматизацию браузера на данном узле без дополнительной настройки.

По умолчанию прокси предоставляет обычную поверхность профилей браузера узла. Если задать nodeHost.browserProxy.allowProfiles, прокси перейдёт в ограничительный режим: обращение к профилям вне списка разрешений будет отклоняться, а маршруты создания и удаления постоянных профилей через прокси будут заблокированы.

При необходимости отключите его на узле:

{  nodeHost: {    browserProxy: {      enabled: false,    },  },}

Запуск (на переднем плане)

openclaw node run --host <gateway-host> --port 18789

Параметры:

• --host <host>: хост WebSocket Gateway (по умолчанию: 127.0.0.1)
• --port <port>: порт WebSocket Gateway (по умолчанию: 18789)
• --context-path <path>: путь контекста WebSocket Gateway (например, /openclaw-gw). Добавляется к URL WebSocket.
• --tls: использовать TLS для подключения к Gateway
• --no-tls: принудительно использовать незашифрованное подключение к Gateway, даже если в локальной конфигурации Gateway включён TLS
• --tls-fingerprint <sha256>: ожидаемый отпечаток сертификата TLS (sha256)
• --node-id <id>: переопределить устаревший идентификатор экземпляра клиента, хранящийся в node.json (не сбрасывает сопряжение)
• --display-name <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).

openclaw node install --host <gateway-host> --port 18789

Параметры:

• --host <host>: хост WebSocket Gateway (по умолчанию: 127.0.0.1)
• --port <port>: порт WebSocket Gateway (по умолчанию: 18789)
• --context-path <path>: путь контекста WebSocket Gateway (например, /openclaw-gw). Добавляется к URL WebSocket.
• --tls: использовать TLS для подключения к Gateway
• --tls-fingerprint <sha256>: ожидаемый отпечаток сертификата TLS (sha256)
• --node-id <id>: переопределить устаревший идентификатор экземпляра клиента, хранящийся в node.json (не сбрасывает сопряжение)
• --display-name <name>: переопределить отображаемое имя узла
• --runtime <runtime>: среда выполнения службы (node)
• --force: переустановить или перезаписать уже установленную службу

Управление службой:

openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw 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.

В противном случае одобрите запрос вручную:

openclaw devices listopenclaw devices approve <requestId>

Просмотрите локальную идентичность узла, с которой Gateway сверяет данные:

openclaw node identity --json

Команда выводит идентификатор устройства и открытый ключ из identity/device.json и никогда не создаёт и не изменяет файлы идентичности.

В строго контролируемых сетях узлов оператор Gateway может явно включить автоматическое одобрение первичного сопряжения узлов из доверенных диапазонов CIDR:

{  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-id изменяет только идентификатор экземпляра клиента в node.json. Он не изменяет криптографический идентификатор устройства и не удаляет данные аутентификации сопряжения. Аналогично, удаление только node.json не сбрасывает сопряжение. Чтобы отозвать и повторно сопрячь узел:

1. На Gateway выполните openclaw nodes remove --node <id|name|ip>.
2. На узле перезапустите установленную службу с помощью openclaw node restart либо остановите и снова выполните команду переднего плана openclaw node run. Это запустит процесс сопряжения устройства. Если openclaw devices list не показывает запрос, а узел сообщает AUTH_DEVICE_TOKEN_MISMATCH, перезапустите службу или повторно выполните команду ещё раз. Отклонённая попытка удаляет отозванный локальный токен; при следующей попытке можно будет запросить сопряжение.
3. На Gateway выполните openclaw devices list, затем openclaw devices approve <deviceRequestId>.
4. Снова перезапустите узел или повторно выполните его команду. Клиент, приостановленный для сопряжения, не возобновляет работу автоматически после одобрения; это повторное подключение создаёт отдельный запрос на поверхность команд.
5. На Gateway выполните openclaw nodes pending, затем openclaw nodes approve <nodeRequestId>.

Эти два идентификатора запросов различаются. Применимая политика доверенных CIDR может автоматически одобрить этап первичного сопряжения устройства; одобрение поверхности команд остаётся отдельной проверкой.

Старые выпуски OpenClaw могли оставлять устаревшее поле token в node.json. Текущая версия OpenClaw не использует это поле и удалит его при следующем сохранении файла хостом узла. Обеспечьте конфиденциальность обоих файлов в identity/; они содержат пару ключей устройства и токены аутентификации.

Одобрения выполнения команд

system.run контролируется локальными одобрениями выполнения команд:

• $OPENCLAW_STATE_DIR/exec-approvals.json или ~/.openclaw/exec-approvals.json, если переменная не задана
• Одобрения выполнения команд
• openclaw approvals --node <id|name|ip> (редактируется на Gateway)

Для одобренного асинхронного выполнения команд на узле OpenClaw подготавливает канонический systemRunPlan перед запросом одобрения. Последующая одобренная пересылка system.run повторно использует этот сохранённый план, поэтому изменения полей команды, рабочего каталога или сеанса после создания запроса на одобрение отклоняются, а не изменяют то, что выполняет узел.

См. также

• Справочник CLI
• Узлы