---
read_when:
    - Реалізація схвалень сполучення Node без інтерфейсу користувача macOS
    - Додавання CLI-процесів для схвалення віддалених вузлів
    - Розширення протоколу Gateway функціями керування Node
summary: Поєднання вузлів під керуванням Gateway (Варіант B) для iOS та інших віддалених вузлів
title: Сполучення, кероване Gateway
x-i18n:
    generated_at: "2026-05-06T03:19:57Z"
    model: gpt-5.5
    provider: openai
    source_hash: 75713e04e37dcbae151d170e2eb459d0e9b9a799c64a10db731b61d7b53998b4
    source_path: gateway/pairing.md
    workflow: 16
---

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

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

## Поняття

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

## Як працює pairing

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

Запити в очікуванні автоматично спливають через **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.pair.verify` - перевірити `{ nodeId, token }`.

Примітки:

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

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

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

</Warning>

## Gating команд вузла (2026.3.31+)

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

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

Це означає:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

## Допоміжні засоби QR pairing

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

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

## Локальність і forwarded headers

Gateway pairing розглядає з’єднання як loopback лише тоді, коли і raw socket,
і будь-які свідчення upstream proxy узгоджуються. Якщо запит надходить через loopback, але
містить заголовки `X-Forwarded-For` / `X-Forwarded-Host` / `X-Forwarded-Proto`,
які вказують на non-local origin, ці forwarded-header свідчення дискваліфікують
твердження про loopback locality. Тоді шлях pairing вимагає явного схвалення
замість того, щоб мовчки трактувати запит як same-host connect. Див.
[Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth) для еквівалентного правила щодо
auth оператора.

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

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

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

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

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

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

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

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

## Пов’язане

- [Channel pairing](/uk/channels/pairing)
- [Nodes](/uk/nodes)
- [Devices CLI](/uk/cli/devices)