OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Сполучення Node

Сполучення Node має два рівні, обидва зберігаються в записі сполученого пристрою в базі даних стану SQLite Gateway:

  • Сполучення пристрою (роль node) контролює рукостискання connect. Див. Автоматичне схвалення пристроїв із довірених CIDR нижче та Сполучення каналів.
  • Схвалення можливостей Node (node.pair.*) визначає, які оголошені можливості/команди може надавати підключений Node. Gateway є джерелом істини; інтерфейси користувача (застосунок macOS, інтерфейс керування) — це фронтенди, які схвалюють або відхиляють запити, що очікують розгляду.

Колишнього окремого сховища сполучень Node (nodes/paired.json з окремим для кожного Node токеном, вилученим зі шляху підключення в січні 2026 року) більше немає: Gateway під час запуску одноразово переносять усі залишкові рядки до записів пристроїв та архівують застарілі файли із суфіксом .migrated. Підтримку застарілого мосту TCP видалено.

Як працює схвалення можливостей

  1. Node підключається до WS Gateway (цей крок контролюється сполученням пристрою).
  2. Gateway порівнює оголошений набір можливостей/команд зі схваленим; нові або розширені набори зберігають запит, що очікує розгляду, у записі пристрою та генерують node.pair.requested.
  3. Ви схвалюєте або відхиляєте запит (через CLI або інтерфейс користувача).
  4. До схвалення команди Node залишаються відфільтрованими; схвалення відкриває оголошений набір з урахуванням звичайної політики команд.

Запити, що очікують розгляду, автоматично завершують строк дії через 5 хвилин після останньої повторної спроби Node — Node, який активно перепідключається, підтримує свій єдиний запит, що очікує розгляду, активним замість створення нового запиту (і запиту на схвалення) для кожної спроби.

Робочий процес CLI (зручний для роботи без графічного інтерфейсу)

bash
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 показує сполучені/підключені Node та їхні можливості.

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

Події:

  • node.pair.requested — генерується під час створення нового запиту, що очікує розгляду.
  • node.pair.resolved — генерується, коли запит схвалено, відхилено або строк його дії завершився.

Методи:

  • node.pair.list — вивести список Node, що очікують розгляду, і сполучених Node (operator.pairing).
  • node.pair.approve — схвалити запит, що очікує розгляду.
  • node.pair.reject — відхилити запит, що очікує розгляду.
  • node.pair.remove — видалити сполучений Node. Це відкликає роль node пристрою у сховищі сполучених пристроїв, разом із нею видаляє схвалений набір можливостей Node та робить недійсними/відключає сеанси цього пристрою з роллю Node. Пристрій із кількома ролями (наприклад, який також має роль operator) зберігає свій рядок і лише втрачає роль node; рядок пристрою лише з роллю Node видаляється. Авторизація: operator.pairing може видаляти рядки Node без ролі оператора; викликач із токеном пристрою, який відкликає власну роль Node на пристрої з кількома ролями, додатково потребує operator.admin.
  • node.rename — перейменувати видиме оператору ім’я сполученого Node.

Видалено у версії 2026.7: node.pair.request і node.pair.verify. Запити, що очікують розгляду, створюються самим Gateway під час підключення Node, а окремого токена для кожного Node, який вони обслуговували, більше не існує; автентифікація Node використовує токен сполучення пристрою.

Примітки:

  • Перепідключення з незміненим набором повторно використовують запит, що очікує розгляду; повторні запити оновлюють збережені метадані Node й останній знімок оголошених команд зі списку дозволених для перегляду оператором.
  • Рівні областей доступу оператора та перевірки під час схвалення узагальнено в розділі Області доступу оператора.
  • node.pair.approve використовує оголошені команди із запиту, що очікує розгляду, для застосування додаткових областей доступу для схвалення:
    • запит без команд: operator.pairing
    • запит команд без виконання: operator.pairing + operator.write
    • запит system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Контроль команд Node (2026.3.31+)

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

Це означає:

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

Межі довіри для подій Node (2026.3.31+)

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

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

Автоматичне схвалення пристроїв із перевіркою через SSH (типово)

Перше сполучення пристрою з role: node із приватної/CGNAT-адреси автоматично схвалюється, коли Gateway може довести володіння машиною через SSH: він підключається назад до хоста сполучення (BatchMode, StrictHostKeyChecking=yes), виконує там openclaw node identity --json і схвалює лише тоді, коли віддалені ідентифікатор пристрою та відкритий ключ точно збігаються із запитом, що очікує розгляду. Саме збіг ключів робить це безпечним: самої доступності ніколи недостатньо для схвалення, тому співмешканці NAT, інші користувачі спільного хоста та підміна в LAN переходять до звичайного запиту.

Увімкнено типово. Вимоги для спрацювання:

  • Користувач процесу Gateway (або sshVerify.user) може підключитися до хоста Node через SSH неінтерактивно (ключі/агент; Tailscale SSH також працює), а ключ хоста вже є довіреним.
  • openclaw визначається у віддаленому PATH для неінтерактивного sh -lc.
  • IP-адреса підключення є прямою (без проксі та не local loopback) приватною адресою, ULA, локальною адресою каналу або адресою CGNAT чи збігається з sshVerify.cidrs, якщо це значення задано.
  • Та сама нижня межа придатності, що й для схвалення довірених CIDR: лише нове сполучення Node без областей доступу; оновлення, браузери, інтерфейс керування та вебчат завжди потребують підтвердження.

Поки виконується перевірка, клієнту Node повідомляється продовжувати повторні спроби (wait_then_retry) замість призупинення для ручного схвалення; якщо перевірка завершується невдало, наступна спроба переходить до звичайного процесу із запитом. Для цілей із невдалою перевіркою застосовується короткий період очікування (5 хвилин після розбіжності ключів).

Схвалені пристрої записують approvedVia: "ssh-verified", а їхній перший оголошений набір можливостей схвалюється на тому самому кроці — збіг ключів уже доводить, що Node працює під обліковим записом оператора на машині, якою він володіє, що відповідає твердженню ручного схвалення можливостей. Подальші розширення набору все одно потребують підтвердження.

Посилення захисту або вимкнення:

json5
{  gateway: {    nodes: {      pairing: {        // Disable entirely:        sshVerify: false,        // ...or scope/tune the probe:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

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

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

  • запит позначено як silent (Gateway позначає перший набір можливостей як тихий, якщо сполучення пристрою було схвалено неінтерактивно), і
  • застосунок може перевірити SSH-з’єднання з хостом Gateway від імені того самого користувача.

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

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

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

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

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

  • Вимкнено, якщо gateway.nodes.pairing.autoApproveCidrs не задано.
  • Загального режиму автоматичного схвалення для LAN або приватної мережі не існує; автоматичне схвалення з перевіркою через SSH (вище) потребує криптографічного збігу ключа пристрою, а не лише мережевої близькості.
  • Придатним є лише новий запит сполучення пристрою з role: node без запитаних областей доступу.
  • Клієнти оператора, браузера, інтерфейсу керування та вебчату залишаються в ручному режимі.
  • Оновлення ролі, області доступу, метаданих і відкритого ключа залишаються ручними.
  • Шляхи заголовків довіреного проксі через local loopback на тому самому хості непридатні, оскільки цей шлях можуть підмінити локальні викликачі.

Очищення замінених тихих сполучень

Неінтерактивні схвалення записують своє походження в рядку сполученого пристрою: локальні схвалення за політикою того самого хоста як silent, схвалення Node із довірених CIDR як trusted-cidr, схвалення Node з перевіркою через SSH як ssh-verified. Клієнти, чий каталог стану є ефемерним (тимчасові домашні каталоги, контейнери, окремі пісочниці для кожного запуску), створюють нову пару ключів пристрою під час кожного запуску, і кожен запуск тихо сполучається повторно як цілком новий пристрій — без очищення список сполучених пристроїв збільшується на один застарілий рядок із кожним запуском.

Коли Gateway тихо схвалює локальне сполучення пристрою, він вилучає старіші записи, схвалені як silent, що належать до того самого кластера клієнтів (збігаються clientId, clientMode і видиме ім’я) та наразі не підключені. Локальні клієнти працюють на самому хості Gateway, тому ключ кластера не може відповідати іншій машині. Токени вилучених рядків негайно стають недійсними; усі відповідні застарілі записи сполучення Node очищуються, а подія видалення node.pair.resolved транслюється.

Межі:

  • Придатними як ініціатори й цілі є лише записи, останнє схвалення яких було локальним на тому самому хості (silent). Сполучення з довірених CIDR і перевіркою через SSH охоплюють різні хости, де видимі метадані не є ідентичністю машини, тому вони ніколи не видаляються автоматично — для них використовуйте очищення в інтерфейсі керування або openclaw nodes remove.
  • Сполучення, схвалені власником, і сполучення за QR-кодом/кодом налаштування (початкового завантаження) ніколи не видаляються автоматично. Записи, схвалені до появи відстеження походження, залишаються захищеними навіть після пізнішого тихого повторного схвалення того самого ідентифікатора пристрою.
  • Підключені наразі пристрої пропускаються, тому паралельні локальні сеанси з окремими каталогами стану зберігають свої токени, поки вони активні. Записи, схвалені протягом останньої хвилини, також пропускаються, щоб одночасні рукостискання сполучення не могли вилучити одне одного до реєстрації їхніх з’єднань.
  • Задіяні клієнти за визначенням є локальними, тому вони тихо сполучаються повторно під час наступного підключення.

Автоматичне схвалення оновлення метаданих

Коли вже сполучений пристрій перепідключається лише з некритичними змінами метаданих (наприклад, видимого імені або підказок щодо платформи клієнта), OpenClaw розглядає це як metadata-upgrade. Тихе автоматичне схвалення має вузьку сферу: воно застосовується лише до довірених локальних перепідключень не з браузера, які вже довели володіння локальними або спільними обліковими даними, включно з перепідключеннями нативного застосунку на тому самому хості після змін метаданих версії ОС. Клієнти браузера/інтерфейсу керування та віддалені клієнти й надалі використовують явний процес повторного схвалення. Оновлення областей доступу (від читання до запису/адміністрування) та зміни відкритого ключа не придатні для автоматичного схвалення metadata-upgrade; вони залишаються явними запитами на повторне схвалення.

Допоміжні засоби сполучення за QR-кодом

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

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

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

Під час сполучення Gateway вважає з’єднання таким, що походить із local loopback, лише коли це підтверджують як необроблений сокет, так і всі дані від проміжного проксі. Якщо запит надходить через local loopback, але містить дані заголовка Forwarded, будь-якого заголовка X-Forwarded-* або X-Real-IP, ці дані переспрямованих заголовків спростовують твердження про локальність у local loopback, і шлях сполучення потребує явного схвалення замість того, щоб неявно вважати запит підключенням із того самого хоста. Відповідне правило для автентифікації оператора див. в розділі Автентифікація довіреного проксі.

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

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

  • ~/.openclaw/state/openclaw.sqlite (сполучені пристрої з автентифікацією пристроїв, схвалені інтерфейси вузлів, запити на інтерфейси, що очікують на розгляд, запити на сполучення пристроїв, що очікують на розгляд, і токени початкового завантаження)

Якщо ви перевизначите OPENCLAW_STATE_DIR, база даних переміститься разом із ним. Gateway, оновлені з випусків зі сховищами JSON, імпортують їх під час запуску та залишають архіви devices/*.json.migrated і nodes/*.json.migrated.

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

  • Токени пристроїв є секретами; вважайте базу даних стану конфіденційною.
  • Для ротації токена пристрою використовується openclaw devices rotate / device.token.rotate.

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

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

Пов’язані матеріали

Was this useful?
On this page

On this page