Перейти до основного вмісту

​
Прив’язка, якою володіє Gateway (варіант B)

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

​
Поняття

  • Очікувальний запит: вузол попросився приєднатися; потребує підтвердження.
  • Прив’язаний вузол: підтверджений вузол із виданим токеном автентифікації.
  • Транспорт: endpoint Gateway WS пересилає запити, але не вирішує, членство. (Підтримку застарілого TCP bridge видалено.)

​
Як працює прив’язка

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

​
Сценарій CLI (дружній до headless)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
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.verify — перевірити { nodeId, token }.
Примітки:
  • node.pair.request є ідемпотентним для кожного вузла: повторні виклики повертають той самий очікувальний запит.
  • Повторні запити для того самого очікувального вузла також оновлюють збережені метадані вузла і найновіший allowlist-знімок оголошених команд для видимості оператора.
  • Підтвердження завжди генерує новий токен; 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
Важливо:
  • Прив’язка вузла — це сценарій довіри/ідентичності плюс видача токена.
  • Вона не закріплює живу поверхню команд вузла для кожного вузла окремо.
  • Живі команди вузла надходять із того, що вузол оголошує під час connect після застосування глобальної політики команд вузлів gateway (gateway.nodes.allowCommands / denyCommands).
  • Політика allow/ask для system.run для кожного вузла живе на самому вузлі в exec.approvals.node.*, а не в записі прив’язки.

​
Керування командами вузла (2026.3.31+)

Несумісна зміна: починаючи з 2026.3.31, команди вузлів вимкнено, доки не підтверджено прив’язку вузла. Самої лише прив’язки пристрою більше недостатньо для відкриття оголошених команд вузла.
Коли вузол підключається вперше, запит на прив’язку створюється автоматично. Доки цей запит не буде підтверджено, усі очікувальні команди вузла від цього вузла фільтруються й не виконуються. Щойно довіру встановлено через підтвердження прив’язки, оголошені команди вузла стають доступними згідно зі звичайною політикою команд. Це означає:
  • Вузли, які раніше покладалися лише на прив’язку пристрою для відкриття команд, тепер мають завершити прив’язку вузла.
  • Команди, поставлені в чергу до підтвердження прив’язки, відкидаються, а не відкладаються.

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

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

​
Автоматичне підтвердження (застосунок macOS)

Застосунок macOS може за бажанням спробувати тихе підтвердження, коли:
  • запит позначено як silent, і
  • застосунок може перевірити SSH-з’єднання з хостом gateway від того самого користувача.
Якщо тихе підтвердження не вдається, використовується звичайне запрошення “Підтвердити/Відхилити”.

​
Зберігання (локальне, приватне)

Стан прив’язки зберігається в каталозі state Gateway (типово ~/.openclaw):
  • ~/.openclaw/nodes/paired.json
  • ~/.openclaw/nodes/pending.json
Якщо ви перевизначаєте OPENCLAW_STATE_DIR, каталог nodes/ переміщується разом із ним. Примітки щодо безпеки:
  • Токени — це секрети; ставтеся до paired.json як до чутливого файла.
  • Ротація токена потребує повторного підтвердження (або видалення запису вузла).

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

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