---
read_when:
    - Реалізація схвалень сполучення вузлів без macOS UI
    - Додавання потоків CLI для затвердження віддалених вузлів
    - Розширення протоколу Gateway керуванням вузлами
summary: Створення пари вузлів, кероване Gateway (варіант B), для iOS та інших віддалених вузлів
title: Сполучення, яким володіє Gateway
x-i18n:
    generated_at: "2026-06-27T17:35:16Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: aefddafaef419fc59b04ee17dae8ef21685b4f514f4286530bf07362663a8996
    source_path: gateway/pairing.md
    workflow: 16
---

У паруванні, яким володіє Gateway, **Gateway** є джерелом істини щодо того, яким вузлам
дозволено приєднуватися. UI (застосунок macOS, майбутні клієнти) є лише фронтендами, які
схвалюють або відхиляють запити, що очікують.

**Важливо:** вузли WS використовують **парування пристрою** (роль `node`) під час `connect`.
`node.pair.*` — це окреме сховище парування, і воно **не** контролює рукостискання WS.
Цей потік використовують лише клієнти, які явно викликають `node.pair.*`.

## Поняття

- **Запит, що очікує**: вузол попросив приєднатися; потребує схвалення.
- **Спарений вузол**: схвалений вузол із виданим токеном автентифікації.
- **Транспорт**: кінцева точка WS Gateway переспрямовує запити, але не вирішує
  членство. (Підтримку застарілого TCP-моста вилучено.)

## Як працює парування

1. Вузол підключається до WS Gateway і запитує парування.
2. Gateway зберігає **запит, що очікує**, і надсилає `node.pair.requested`.
3. Ви схвалюєте або відхиляєте запит (CLI або UI).
4. Після схвалення Gateway видає **новий токен** (токени ротуються під час повторного парування).
5. Вузол повторно підключається з токеном і тепер є "paired".

Запити, що очікують, автоматично спливають через **5 хвилин**.

## Робочий процес CLI (зручний для headless)

```bash
openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"
```

`nodes status` показує спарені/підключені вузли та їхні можливості.

## Поверхня API (протокол gateway)

Події:

- `node.pair.requested` - надсилається, коли створено новий запит, що очікує.
- `node.pair.resolved` - надсилається, коли запит схвалено/відхилено/термін дії сплив.

Методи:

- `node.pair.request` - створити або повторно використати запит, що очікує.
- `node.pair.list` - перелічити вузли, що очікують, і спарені вузли (`operator.pairing`).
- `node.pair.approve` - схвалити запит, що очікує (видає токен).
- `node.pair.reject` - відхилити запит, що очікує.
- `node.pair.remove` - видалити спарений вузол. Для парувань на основі пристроїв це
  відкликає роль `node` пристрою: змінює `devices/paired.json` і
  робить недійсними/відключає сесії цього пристрою з роллю node. Пристрій із **змішаними ролями**
  (наприклад, він також має `operator`) зберігає свій рядок і втрачає лише роль `node`;
  рядок пристрою лише з node видаляється. Також видаляється будь-який відповідний застарілий
  запис парування вузла, яким володіє gateway. Authz: `operator.pairing` може видаляти
  рядки вузлів не-operator; викликач із device-token, який відкликає свою **власну** роль node на
  пристрої зі змішаними ролями, додатково потребує `operator.admin`.
- `node.pair.verify` - перевірити `{ nodeId, token }`.

Примітки:

- `node.pair.request` є ідемпотентним для кожного вузла: повторні виклики повертають той самий
  запит, що очікує.
- Повторні запити для того самого вузла, що очікує, також оновлюють збережені метадані вузла
  та останній allowlisted знімок оголошених команд для видимості оператору.
- Схвалення **завжди** генерує свіжий токен; `node.pair.request` ніколи не повертає токен.
- Рівні області дії оператора та перевірки під час схвалення підсумовано в
  [Області дії оператора](/uk/gateway/operator-scopes).
- Запити можуть містити `silent: true` як підказку для потоків автоматичного схвалення.
- `node.pair.approve` використовує оголошені команди запиту, що очікує, щоб застосувати
  додаткові області схвалення:
  - запит без команд: `operator.pairing`
  - запит команди не exec: `operator.pairing` + `operator.write`
  - запит `system.run` / `system.run.prepare` / `system.which`:
    `operator.pairing` + `operator.admin`

<Warning>
Парування вузла — це потік довіри та ідентичності плюс видача токена. Воно **не** закріплює живу поверхню команд вузла для кожного вузла.

- Живі команди вузла надходять із того, що вузол оголошує під час підключення після застосування глобальної політики команд вузлів gateway (`gateway.nodes.allowCommands` і `denyCommands`).
- Політика дозволу й запиту для `system.run` на рівні вузла живе на вузлі в `exec.approvals.node.*`, а не в записі парування.

</Warning>

## Контроль команд вузла (2026.3.31+)

<Warning>
**Критична зміна:** Починаючи з `2026.3.31`, команди вузла вимкнено, доки парування вузла не буде схвалено. Самого парування пристрою більше недостатньо, щоб відкрити оголошені команди вузла.
</Warning>

Коли вузол підключається вперше, парування запитується автоматично. Доки запит на парування не схвалено, усі команди вузла, що очікують від цього вузла, фільтруються й не виконуватимуться. Після встановлення довіри через схвалення парування оголошені команди вузла стають доступними з урахуванням звичайної політики команд.

Це означає:

- Вузли, які раніше покладалися лише на парування пристрою, щоб відкрити команди, тепер мають завершити парування вузла.
- Команди, поставлені в чергу до схвалення парування, відкидаються, а не відкладаються.

## Межі довіри подій вузла (2026.3.31+)

<Warning>
**Критична зміна:** Запуски, ініційовані вузлом, тепер залишаються на зменшеній довіреній поверхні.
</Warning>

Підсумки, ініційовані вузлом, і пов’язані події сесії обмежено призначеною довіреною поверхнею. Потоки, керовані сповіщеннями або запущені вузлом, які раніше покладалися на ширший доступ до інструментів хоста чи сесії, можуть потребувати коригування. Це посилення гарантує, що події вузла не можуть ескалювати до доступу до інструментів на рівні хоста поза межами довіри вузла.

Тривалі оновлення присутності вузла дотримуються тієї самої межі ідентичності. Подія `node.presence.alive`
приймається лише від автентифікованих сесій пристроїв вузла й оновлює метадані парування лише тоді, коли
ідентичність пристрою/вузла вже спарена. Самостійно оголошених значень `client.id` недостатньо для запису
стану last-seen.

## Автоматичне схвалення (застосунок macOS)

Застосунок macOS може за бажанням спробувати **тихе схвалення**, коли:

- запит позначено `silent`, і
- застосунок може перевірити SSH-з’єднання з хостом gateway за допомогою того самого користувача.

Якщо тихе схвалення не вдається, він повертається до звичайного запиту "Approve/Reject".

## Автоматичне схвалення пристроїв за довіреним CIDR

Парування пристроїв WS для `role: node` за замовчуванням залишається ручним. Для приватних
мереж вузлів, де Gateway уже довіряє мережевому шляху, оператори можуть
увімкнути це явно заданими CIDR або точними IP:

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

Межа безпеки:

- Вимкнено, коли `gateway.nodes.pairing.autoApproveCidrs` не задано.
- Немає універсального режиму автоматичного схвалення LAN або приватної мережі.
- Придатне лише свіже парування пристрою `role: node` без запитаних областей дії.
- Клієнти operator, browser, Control UI і WebChat залишаються ручними.
- Оновлення ролі, області дії, метаданих і публічного ключа залишаються ручними.
- Шляхи заголовків довіреного проксі same-host loopback непридатні, оскільки цей
  шлях можуть підробити локальні викликачі.

## Автоматичне схвалення metadata-upgrade

Коли вже спарений пристрій повторно підключається лише зі змінами нечутливих метаданих
(наприклад, відображуваного імені або підказок платформи клієнта), OpenClaw розглядає
це як `metadata-upgrade`. Тихе автоматичне схвалення вузьке: воно застосовується лише
до довірених небраузерних локальних повторних підключень, які вже довели володіння локальними
або спільними обліковими даними, включно з повторними підключеннями нативного застосунку на тому самому хості після змін
метаданих версії OS. Клієнти browser/Control UI і віддалені клієнти все ще
використовують явний потік повторного схвалення. Підвищення областей дії (read до write/admin) і
зміни публічного ключа **не** придатні для автоматичного схвалення metadata-upgrade -
вони залишаються явними запитами на повторне схвалення.

## Помічники QR-парування

`/pair qr` відтворює корисне навантаження парування як структуровані медіа, щоб мобільні та
браузерні клієнти могли сканувати його напряму.

Видалення пристрою також очищає будь-які застарілі запити на парування, що очікують, для цього
id пристрою, тому `nodes pending` не показує осиротілих рядків після відкликання.

## Локальність і переслані заголовки

Gateway-парування вважає з’єднання loopback лише тоді, коли і сирий сокет,
і будь-які докази upstream-проксі узгоджуються. Якщо запит надходить на loopback, але
містить докази заголовків `Forwarded`, будь-яких `X-Forwarded-*` або `X-Real-IP`, ці
докази пересланих заголовків дискваліфікують твердження про loopback-локальність. Шлях парування
потім потребує явного схвалення замість того, щоб тихо вважати запит
підключенням з того самого хоста. Див. [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth) для
еквівалентного правила щодо автентифікації operator.

## Сховище (локальне, приватне)

Стан парування зберігається в каталозі стану Gateway (за замовчуванням `~/.openclaw`):

- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`

Якщо ви перевизначаєте `OPENCLAW_STATE_DIR`, папка `nodes/` переміщується разом із ним.

Примітки щодо безпеки:

- Токени є секретами; вважайте `paired.json` чутливим.
- Ротація токена потребує повторного схвалення (або видалення запису вузла).

## Поведінка транспорту

- Транспорт є **stateless**; він не зберігає членство.
- Якщо Gateway offline або парування вимкнено, вузли не можуть паруватися.
- Якщо Gateway у remote mode, парування все одно відбувається зі сховищем віддаленого Gateway.

## Пов’язане

- [Парування каналів](/uk/channels/pairing)
- [Вузли](/uk/nodes)
- [CLI пристроїв](/uk/cli/devices)