--- read_when: - Запуск безголового хоста Node - Сполучення вузла не на macOS для system.run summary: Довідник CLI для `openclaw node` (хост Node без графічного інтерфейсу) title: Node x-i18n: generated_at: "2026-07-12T13:05:55Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 076449123d8b3e9cb092a2bd7de311b87b27a128cb381fc343c68d18aeb634a0 source_path: cli/node.md workflow: 16 --- # `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 на хості вузла](/uk/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://`, приймаються 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). ```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` або `bun`) - `--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 і схвалює його за точного збігу ключа пристрою. Це типово ввімкнено; див. [Автоматичне схвалення пристрою з перевіркою через SSH](/uk/gateway/pairing#ssh-verified-device-auto-approval-default) щодо вимог і способу вимкнення (`gateway.nodes.pairing.sshVerify: false`). В іншому разі схваліть вручну за допомогою: ```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`, якщо змінну не задано - [Схвалення виконання](/uk/tools/exec-approvals) - `openclaw approvals --node ` (редагування з Gateway) Для схваленого асинхронного виконання на вузлі OpenClaw готує канонічний `systemRunPlan` перед запитом на підтвердження. Подальше пересилання схваленого `system.run` повторно використовує збережений план, тому зміни полів команди, робочого каталогу або сеансу після створення запиту на схвалення відхиляються, а не змінюють те, що виконує вузол. ## Пов’язані матеріали - [Довідник CLI](/uk/cli) - [Вузли](/uk/nodes)