openclaw node

Запустіть безголовий хост вузла, який підключається до WebSocket Gateway і надає system.run / system.which на цій машині.

Навіщо використовувати хост вузла?

Використовуйте хост вузла, коли потрібно, щоб агенти виконували команди на інших машинах у вашій мережі без установлення на них повноцінної супутньої програми для macOS.

Поширені сценарії використання:

• Виконання команд на віддалених машинах Linux/Windows (серверах збірки, лабораторних машинах, NAS).
• Збереження виконання в пісочниці на Gateway із делегуванням схвалених запусків іншим хостам.
• Надання легкого безголового цільового середовища виконання для автоматизації або вузлів CI.

Виконання й надалі захищене схваленнями виконання та списками дозволів для кожного агента на хості вузла, тож ви можете зберігати доступ до команд обмеженим і явним.

openclaw node run може публікувати інструменти Plugin або інструменти на основі MCP після підключення. Gateway типово довіряє дескрипторам від спареного вузла, водночас вимагаючи, щоб команда кожного дескриптора залишалася в межах схваленої поверхні команд вузла. Агент бачить кожен прийнятий дескриптор як звичайний інструмент Plugin, але виконання все одно проходить через 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://, приймаються local loopback, літерали приватних IP-адрес, хости .local і хости Tailnet *.ts.net. Для інших довірених імен приватного 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 або bun)
• --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 і схвалює його за точного збігу ключа пристрою. Це типово ввімкнено; див. Автоматичне схвалення пристрою з перевіркою через SSH щодо вимог і способу вимкнення (gateway.nodes.pairing.sshVerify: false).

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

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