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.

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

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

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

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

{  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>: переопределить идентификатор экземпляра клиента, хранящийся в общем состоянии SQLite (не сбрасывает сопряжение)
• --display-name <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).

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>: переопределить идентификатор экземпляра клиента, хранящийся в общем состоянии SQLite (не сбрасывает сопряжение)
• --display-name <name>: переопределить отображаемое имя Node
• --runtime <runtime>: среда выполнения службы (node)
• --force: переустановить или перезаписать, если уже установлено

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

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

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

openclaw devices listopenclaw devices approve <requestId>

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

openclaw node identity --json

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

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

{  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, если задано):

--node-id изменяет только идентификатор экземпляра клиента в общем состоянии SQLite. Он не изменяет криптографический идентификатор устройства и не очищает данные аутентификации сопряжения. Перенос устаревшего node.json с помощью openclaw doctor --fix также не сбрасывает сопряжение. Чтобы отозвать и повторно сопрячь Node:

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

Эти два идентификатора запроса различаются. Применимая политика доверенных 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
• openclaw approvals --node <id|name|ip> (редактируется с Gateway)

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

См. также

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