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, Control UI) — це фронтенди, які схвалюють або відхиляють запити, що очікують розгляду.

Колишнього окремого сховища сполучень Node (nodes/paired.json з окремим для кожного Node токеном, вилученим зі шляху підключення в січні 2026 року) більше немає: під час запуску шлюзи одноразово переносять усі залишкові рядки до записів пристроїв і архівують застарілі файли із суфіксом .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, що очікують розгляду та сполучені (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, browser.proxy, fs.listDir або system.execApprovals.get/set: 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, інші користувачі спільного хоста та підміна в локальній мережі переходять до звичайного запиту.

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

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

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

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

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

json5
{  gateway: {    nodes: {      pairing: {        // Повністю вимкнути:        sshVerify: false,        // ...або обмежити/налаштувати перевірку:        // 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 без запитаних областей дії.
  • Клієнти оператора, браузера, Control UI та WebChat залишаються в ручному режимі.
  • Оновлення ролі, області дії, метаданих і відкритого ключа залишаються ручними.
  • Шляхи заголовків довіреного проксі через 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. Тихе автоматичне схвалення має вузьку сферу застосування: воно діє лише для довірених локальних повторних підключень не з браузера, які вже підтвердили володіння локальними або спільними обліковими даними, зокрема для повторних підключень нативних застосунків на тому самому хості після зміни метаданих версії ОС. Клієнти браузера/інтерфейсу керування та віддалені клієнти й надалі використовують явну процедуру повторного схвалення. Розширення області доступу (із читання до запису/адміністрування) і зміни відкритого ключа не підлягають автоматичному схваленню оновлення метаданих; вони залишаються явними запитами на повторне схвалення.

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

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

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

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

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

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

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

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

Якщо перевизначити 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