Сполучення, яким володіє Gateway

У паруванні, яким володіє 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)

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

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

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

Це означає:

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

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

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

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

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

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

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

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

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

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

{  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-локальність. Шлях парування потім потребує явного схвалення замість того, щоб тихо вважати запит підключенням з того самого хоста. Див. Автентифікація довіреного проксі для еквівалентного правила щодо автентифікації operator.

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

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

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

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

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

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

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

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

Пов’язане

• Парування каналів
• Вузли
• CLI пристроїв