---
read_when:
    - Запуск безголового хоста Node
    - Сполучення Node без macOS для system.run
summary: Довідник CLI для `openclaw node` (безголового хоста Node)
title: Node
x-i18n:
    generated_at: "2026-07-16T17:53:42Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: d17b96b8829bef4202ff220d9b20e04c183702f997f669120cb16aa7191235b6
    source_path: cli/node.md
    workflow: 16
---

# `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](/uk/nodes#node-hosted-mcp-servers).

## Проксі браузера (без налаштування)

Хости Node автоматично оголошують проксі браузера, якщо `browser.enabled` не
вимкнено на Node. Це дає агенту змогу використовувати автоматизацію браузера на цьому Node
без додаткового налаштування.

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

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

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

## Запуск (на передньому плані)

```bash
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).

```bash
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`: Повторно встановити або перезаписати, якщо вже встановлено

Керування службою:

```bash
openclaw node status
openclaw node start
openclaw node stop
openclaw node restart
openclaw 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](/uk/gateway/pairing#ssh-verified-device-auto-approval-default)
щодо вимог і способу вимкнення (`gateway.nodes.pairing.sshVerify: false`).

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

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

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

```bash
openclaw node identity --json
```

Команда виводить ідентифікатор пристрою та відкритий ключ із `identity/device.json` і ніколи
не створює та не змінює файли ідентичності.

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

```json5
{
  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`,
якщо задано):

| Стан                                        | Призначення                                                                                                                          |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `state/openclaw.sqlite` (`node_host_config`) | Ідентифікатор екземпляра клієнта, відображуване ім’я та метадані підключення до Gateway. Клієнт надсилає цей ідентифікатор як `instanceId`.                     |
| `identity/device.json`                       | Підписана пара ключів Ed25519 і похідний ідентифікатор пристрою. Для підписаних підключень цей ідентифікатор пристрою є маршрутизованим ідентифікатором Node та ідентичністю спарювання. |
| `identity/device-auth.json`                  | Токени спарених пристроїв, індексовані за криптографічним ідентифікатором пристрою та роллю.                                                                 |

`--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](/uk/tools/exec-approvals)
- `openclaw approvals --node <id|name|ip>` (редагується з Gateway)

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

## Пов’язане

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