---
read_when:
    - Запуск безголового вузла-хоста
    - Сполучення вузла не на macOS для `system.run`
summary: Довідник CLI для `openclaw node` (безголового вузла-хоста)
title: Node
x-i18n:
    generated_at: "2026-04-26T07:00:04Z"
    model: gpt-5.4
    provider: openai
    source_hash: 40f623b163a3c3bcd2d3ff218c5e62a4acba45f7e3f16694d8da62a004b77706
    source_path: cli/node.md
    workflow: 15
---

# `openclaw node`

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

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

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

Поширені випадки використання:

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

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

## Браузерний проксі (нульова конфігурація)

Вузли-хости автоматично анонсують браузерний проксі, якщо `browser.enabled` не
вимкнено на вузлі. Це дає агенту змогу використовувати браузерну автоматизацію на цьому вузлі
без додаткової конфігурації.

За замовчуванням проксі надає звичайну поверхню браузерного профілю вузла. Якщо ви
встановите `nodeHost.browserProxy.allowProfiles`, проксі стане обмежувальним:
спроби звернення до профілів, яких немає в списку дозволених, відхиляються, а маршрути
створення/видалення постійних профілів блокуються через проксі.

За потреби вимкніть його на вузлі:

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

## Запуск (передній план)

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

Параметри:

- `--host <host>`: хост Gateway WebSocket (типово: `127.0.0.1`)
- `--port <port>`: порт Gateway WebSocket (типово: `18789`)
- `--tls`: використовувати TLS для підключення до gateway
- `--tls-fingerprint <sha256>`: очікуваний відбиток TLS-сертифіката (sha256)
- `--node-id <id>`: перевизначити ідентифікатор вузла (очищає токен сполучення)
- `--display-name <name>`: перевизначити відображуване ім’я вузла

## Автентифікація Gateway для вузла-хоста

`openclaw node run` і `openclaw node install` визначають автентифікацію gateway із config/env (без прапорців `--token`/`--password` у командах вузла):

- Спочатку перевіряються `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD`.
- Далі використовується локальний резервний варіант із config: `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`) також можуть використовуватися згідно з правилами пріоритету для remote.
- Визначення автентифікації вузла-хоста враховує лише змінні середовища `OPENCLAW_GATEWAY_*`.

Для вузла, що підключається до не-loopback `ws://` Gateway у довіреній приватній
мережі, установіть `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`. Без цього запуск вузла
завершується в закритому режимі відмови й пропонує використовувати `wss://`, SSH-тунель або Tailscale.
Це opt-in на рівні середовища процесу, а не ключ конфігурації `openclaw.json`.
`openclaw node install` зберігає його в керованому сервісі вузла, якщо змінна
присутня в середовищі команди встановлення.

## Сервіс (фоновий режим)

Установіть безголовий вузол-хост як користувацький сервіс.

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

Параметри:

- `--host <host>`: хост Gateway WebSocket (типово: `127.0.0.1`)
- `--port <port>`: порт Gateway WebSocket (типово: `18789`)
- `--tls`: використовувати TLS для підключення до gateway
- `--tls-fingerprint <sha256>`: очікуваний відбиток TLS-сертифіката (sha256)
- `--node-id <id>`: перевизначити ідентифікатор вузла (очищає токен сполучення)
- `--display-name <name>`: перевизначити відображуване ім’я вузла
- `--runtime <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 повідомляє про термінальну паузу автентифікації токена/пароля/bootstrap, вузол-хост
журналює деталі закриття та завершується з ненульовим кодом, щоб launchd/systemd могли
перезапустити його зі свіжою конфігурацією та обліковими даними. Паузи, що вимагають сполучення,
залишаються в потоці переднього плану, щоб запит, який очікує, можна було схвалити.

## Сполучення

Перше підключення створює запит на очікуване сполучення пристрою (`role: node`) на Gateway.
Схваліть його через:

```bash
openclaw devices list
openclaw devices approve <requestId>
```

У жорстко контрольованих мережах вузлів оператор Gateway може явно ввімкнути
автоматичне схвалення першого сполучення вузлів із довірених CIDR:

```json5
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
```

Це вимкнено за замовчуванням. Це застосовується лише до нового сполучення `role: node` без
запитаних scope. Клієнти operator/browser, Control UI, WebChat, а також оновлення role,
scope, metadata або public key, як і раніше, потребують ручного схвалення.

Якщо вузол повторює сполучення зі зміненими даними автентифікації (role/scopes/public key),
попередній запит у стані очікування замінюється, і створюється новий `requestId`.
Перед схваленням знову виконайте `openclaw devices list`.

Вузол-хост зберігає свій ідентифікатор вузла, токен, відображуване ім’я та інформацію про підключення до gateway у
`~/.openclaw/node.json`.

## Схвалення exec

`system.run` контролюється локальними схваленнями exec:

- `~/.openclaw/exec-approvals.json`
- [Схвалення exec](/uk/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (редагування з Gateway)

Для схваленого асинхронного exec вузла OpenClaw готує канонічний `systemRunPlan`
до показу запиту. Пізніше переспрямування схваленого `system.run` повторно використовує цей збережений
план, тому зміни полів command/cwd/session після створення запиту на схвалення
відхиляються замість зміни того, що виконує вузол.

## Пов’язане

- [Довідник CLI](/uk/cli)
- [Вузли](/uk/nodes)
