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).
• Збереження виконання exec у пісочниці на 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 і схвалює його за точного збігу ключа пристрою. Це ввімкнено за замовчуванням; див. Автоматичне схвалення пристроїв із перевіркою через SSH щодо вимог і способу вимкнення (gateway.nodes.pairing.sshVerify: false).

В іншому разі схваліть вручну за допомогою:

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
• Вузли