Сполучення, кероване Gateway

У 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)

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.
• Запити можуть містити silent: true як підказку для потоків автоматичного схвалення.
• node.pair.approve використовує оголошені команди запиту в очікуванні, щоб застосувати додаткові scope схвалення:
  • запит без команд: operator.pairing
  • запит команди не-exec: operator.pairing + operator.write
  • запит system.run / system.run.prepare / system.which: operator.pairing + operator.admin

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

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

Це означає:

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

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

Підсумки, ініційовані вузлом, і пов’язані події сесії обмежені призначеною довіреною поверхнею. Потоки, керовані сповіщеннями або ініційовані вузлом, які раніше покладалися на ширший доступ до інструментів 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:

{
  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 для еквівалентного правила щодо 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
• Nodes
• Devices CLI