Вузли

Node — це допоміжний пристрій (macOS/iOS/watchOS/Android/без інтерфейсу), який підключається до Gateway за допомогою role: "node" і надає командний інтерфейс (наприклад, canvas.*, camera.*, device.*, notifications.*, system.*) через node.invoke. Більшість Node використовують WebSocket Gateway на порту оператора. Необов’язковий прямий Node Apple Watch використовує підписане HTTPS-опитування на тому самому порту, оскільки watchOS блокує універсальні низькорівневі мережеві з’єднання для звичайних застосунків. Докладніше про протокол: Протокол Gateway.

Застарілий транспорт: Протокол Bridge (TCP JSONL; для поточних Node має лише історичне значення).

macOS також може працювати в режимі Node: застосунок у рядку меню підключається до WS-сервера Gateway як один Node (тому openclaw nodes … працює з цим Mac). Застосунок додає нативні команди Canvas, камери, екрана, сповіщень і керування комп’ютером до того самого командного інтерфейсу хоста Node, який використовує openclaw node run. Не запускайте на цьому Mac другий CLI Node; застосунок запускає відповідне середовище виконання хоста CLI Node як внутрішній робочий процес і залишається єдиним з’єднанням із Gateway та єдиною ідентичністю Node.

Node — це периферійні пристрої, а не шлюзи: вони не запускають службу Gateway, а повідомлення каналів (Telegram, WhatsApp тощо) надходять до Gateway, а не до Node.

Інструкція з усунення несправностей: /nodes/troubleshooting

Сполучення та стан

Node використовують сполучення пристроїв. Під час підключення Node надає підписану ідентичність пристрою; Gateway створює запит на сполучення пристрою для role: node. Схваліть його через CLI пристроїв (або інтерфейс користувача). Для прямого налаштування Apple Watch використовується створений адміністратором короткочасний код налаштування лише для Node, щоб схвалити фіксований набір команд із низьким ризиком; подальше розширення можливостей усе одно потребує звичайного схвалення.

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>

Запити на сполучення в очікуванні спливають через 5 хвилин після останньої повторної спроби пристрою — пристрій, який постійно повторно підключається, підтримує активність свого єдиного запиту в очікуванні (і requestId), замість того щоб створювати новий запит кожні кілька хвилин; повний життєвий цикл запиту та схвалення описано в розділі Сполучення Node. Якщо Node повторює спробу зі зміненими даними автентифікації (роллю/областями дії/відкритим ключем), попередній запит в очікуванні замінюється та створюється новий requestId — клієнти отримують подію device.pair.resolved для заміненого запиту, і перед схваленням слід повторно виконати openclaw devices list.

• nodes status позначає Node як сполучений, коли його роль сполучення пристрою містить node.
• Підключений нативний Mac із дозволом Accessibility може повідомляти про об’єднану активність фізичного введення. Gateway позначає найактуальніший придатний Mac як active, надає агенту стабільну підказку ідентифікатора Node та спрямовує туди сповіщення про підключення Node перед відкладеним резервним маршрутом. Налаштування, конфіденційність, часові параметри та усунення несправностей описано в розділі Присутність за активним комп’ютером.
• Запис сполучення пристрою є довготривалим контрактом схваленої ролі. Ротація токенів відбувається в межах цього контракту; вона не може підвищити роль сполученого Node до ролі, яку ніколи не було надано під час схвалення сполучення.
• node.pair.* (CLI: openclaw nodes pending/approve/reject/remove/rename) — це окреме сховище сполучень Node, яким володіє Gateway і яке відстежує схвалений набір команд та можливостей Node між повторними підключеннями. Воно не контролює автентифікацію транспорту — це робить сполучення пристрою.
• openclaw nodes remove --node <id|name|ip> видаляє сполучення Node. Для Node, пов’язаного з пристроєм, ця дія відкликає роль node пристрою в сховищі сполучених пристроїв і від’єднує сеанси цього пристрою з роллю Node: пристрій зі змішаними ролями зберігає свій рядок і втрачає лише роль node, а рядок пристрою лише з роллю Node видаляється. Також видаляється відповідний запис з окремого сховища сполучень Node. operator.pairing може видаляти рядки Node без ролі оператора на інших пристроях; клієнту з токеном пристрою, який відкликає власну роль Node на пристрої зі змішаними ролями, додатково потрібен operator.admin.
• Область схвалення відповідає командам, оголошеним у запиті в очікуванні:
  • запит без команд: operator.pairing
  • команди Node, відмінні від виконання: operator.pairing + operator.write
  • system.run / system.run.prepare / system.which: operator.pairing + operator.admin

Розбіжність версій і порядок оновлення

WebSocket Gateway приймає автентифіковані клієнти Node у межах вікна протоколів N-1. Отже, поточний Gateway v4 приймає Node v3, коли підключення оголошує як role: "node", так і client.mode: "node". Сеанси оператора та інтерфейсу користувача все одно мають використовувати поточний протокол.

Для поетапного оновлення парку спочатку оновіть Gateway, а потім кожен Node. Node версії N-1 залишається видимим і керованим під час оновлення; Gateway записує в журнал legacy node protocol accepted із рекомендацією щодо оновлення. Сполучення, автентифікація пристрою, списки дозволених команд і схвалення виконання продовжують діяти. Можливості й команди, якими володіють Plugin, залишаються прихованими, доки Node не буде оновлено до поточного протоколу. Node, старіші за N-1, потребують позасмугового оновлення перед повторним підключенням.

Прямий HTTPS-транспорт watchOS потребує поточної версії протоколу; оновіть застосунок годинника разом із Gateway, перш ніж увімкнути прямий режим.

Віддалений хост Node (system.run)

Використовуйте хост Node, коли Gateway працює на одному комп’ютері, а команди мають виконуватися на іншому. Модель усе одно взаємодіє з Gateway; Gateway пересилає виклики exec до хоста Node, коли вибрано host=node.

Примітка щодо схвалення:

• Запуски Node, що потребують схвалення, прив’язуються до точного контексту запиту. Шлях виконання готує канонічний systemRunPlan до схвалення; після його надання Gateway пересилає цей збережений план, а не змінені викликачем пізніше поля команди/cwd/сеансу, і повторно перевіряє робочий каталог перед запуском.
• Для прямого виконання файлів оболонки або середовища виконання OpenClaw також у режимі найкращих зусиль прив’язує один конкретний локальний файловий операнд і забороняє запуск, якщо цей файл змінюється до виконання.
• Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора або середовища виконання, виконання зі схваленням забороняється замість удаваного повного охоплення середовища виконання. Для ширшої семантики інтерпретатора використовуйте ізоляцію, окремі хости або явний довірений список дозволів чи повний робочий процес.

Запуск хоста Node (на передньому плані)

На комп’ютері Node:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

node run також приймає --context-path (шлях контексту WS Gateway), --tls, --tls-fingerprint <sha256> та --node-id (перевизначає застарілий ідентифікатор екземпляра клієнта; це не скидає сполучення).

Віддалений Gateway через тунель SSH (прив’язка до loopback)

Якщо Gateway прив’язаний до loopback (gateway.bind=loopback, типово для локального режиму), віддалені хости Node не можуть підключитися безпосередньо. Створіть тунель SSH і спрямуйте хост Node на локальний кінець тунелю.

Приклад (хост Node -> хост Gateway):

# Термінал A (залиште запущеним): перенаправлення локального 18790 -> gateway 127.0.0.1:18789ssh -N -L 18790:127.0.0.1:18789 user@gateway-host # Термінал B: експортуйте токен gateway і підключіться через тунельexport OPENCLAW_GATEWAY_TOKEN="<gateway-token>"openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

Примітки:

• openclaw node run підтримує автентифікацію за токеном або паролем.
• Бажано використовувати змінні середовища: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• Резервна конфігурація: gateway.auth.token / gateway.auth.password.
• У локальному режимі хост Node навмисно ігнорує gateway.remote.token / gateway.remote.password.
• У віддаленому режимі gateway.remote.token / gateway.remote.password можуть використовуватися відповідно до правил пріоритету віддаленого режиму.
• Якщо налаштовано активні локальні SecretRefs gateway.auth.*, але їх не вдається вирішити, автентифікація хоста Node завершується закритою відмовою.
• Визначення автентифікації хоста Node враховує лише змінні середовища OPENCLAW_GATEWAY_*.

Запуск хоста Node (як служби)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"openclaw node startopenclaw node restart

node install також приймає --context-path, --tls, --tls-fingerprint, --node-id (лише застарілий ідентифікатор екземпляра клієнта), --runtime <node> (типово: Node) і --force для повторного встановлення. Також доступні node status, node stop і node uninstall.

Сполучення та назва

На хості Gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

Якщо Node повторює спробу зі зміненими даними автентифікації, повторно виконайте openclaw devices list і схваліть поточний requestId.

Варіанти іменування:

• --display-name у openclaw node run / openclaw node install (зберігається у спільному рядку SQLite node_host_config разом з ідентифікатором екземпляра клієнта та метаданими підключення до Gateway).
• openclaw nodes rename --node <id|name|ip> --name "Build Node" (перевизначення Gateway).

Сервери MCP на хості Node

Налаштуйте сервери MCP у openclaw.json на комп’ютері Node, а не на Gateway:

{  nodeHost: {    mcp: {      servers: {        localDocs: {          command: "npx",          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],          toolFilter: {            include: ["read_*", "search"],          },        },        internalApi: {          url: "https://mcp.internal.example/mcp",          transport: "streamable-http",          headers: {            Authorization: "Bearer ${INTERNAL_MCP_TOKEN}",          },        },      },    },  },}

Хост Node без інтерфейсу запускає ці сервери, отримує список їхніх інструментів і публікує дескриптори після підключення. Виклики інструментів повертаються до цього Node через mcp.tools.call.v1; Gateway не потребує відповідної конфігурації MCP або JS- плагіна. Сервери MCP з OAuth не підтримуються цим шляхом v1 на хості Node.

Поточні хости Node оголошують вбудоване сімейство команд mcp.tools.call.v1 під час початкового сполучення, навіть якщо не налаштовано жодного сервера MCP. Node, сполучений у старішій версії OpenClaw, може запитати одноразове оновлення командного інтерфейсу після оновлення хоста Node. Додавання, видалення або фільтрування серверів після цього не потребує повторного сполучення, оскільки схвалене сімейство команд не змінюється. Перезапустіть openclaw node run або openclaw node restart, щоб застосувати зміни конфігурації MCP Node; хост Node не відстежує цю конфігурацію.

Оператори Gateway можуть ігнорувати всі видимі агенту інструменти, опубліковані сполученими Node, включно з інструментами MCP на хостах Node, за допомогою gateway.nodes.pluginTools.enabled: false. Точні заборони команд, як-от gateway.nodes.denyCommands: ["mcp.tools.call.v1"], також блокують виконання.

Skills на хості Node

Установіть Skills у каталозі активних Skills OpenClaw на комп’ютері Node, типово ~/.openclaw/skills. OPENCLAW_HOME, OPENCLAW_STATE_DIR і OPENCLAW_CONFIG_PATH переміщують цей активний профіль. OPENCLAW_STATE_DIR має пріоритет для Skills; інакше skills/ розташований поруч зі шляхом, який виводить openclaw config file. Хост Node без інтерфейсу публікує дійсні файли SKILL.md після підключення, а Gateway додає їх до знімків Skills агента лише доки цей Node залишається підключеним. Назва кожного каталогу Skill має збігатися з полем frontmatter name, щоб абстрактний локатор Node зіставлявся з одним записом без додавання ще одного поля протоколу.

Початкове сполучення з роллю вузла схвалює публікацію навичок. Додавання, видалення або змінення навичок не потребує повторного сполучення чи зміни конфігурації Gateway. Перезапустіть openclaw node run або openclaw node restart після змінення файлів навичок вузла; хост вузла не відстежує каталог навичок.

Записи навичок, розміщених на вузлі, ідентифікують свій вузол і містять місце виконання. Файли навичок, відносні шляхи, на які вони посилаються, і двійкові файли залишаються на цьому вузлі. Агент читає оголошене розташування node://.../SKILL.md за допомогою звичайного інструмента read. file_fetch приймає схвалені оператором абсолютні шляхи вузла, а не локатори навичок вузла; натомість середовища виконання без звичайного інструмента читання можуть запустити cat SKILL.md через exec host=node node=<node-id>, використовуючи оголошений каталог node://.../skills/<name> як workdir. Файли й двійкові файли, на які є посилання, використовують ту саму ціль виконання та робочий каталог. Хост вузла визначає цей локатор відносно свого активного каталогу стану OpenClaw, тому відносні шляхи визначаються на вузлі, а не на машині Gateway. Вузол публікації повинен мати схвалений system.run, а політика виконання агента повинна дозволяти host=node; інакше навичка не потрапляє до знімка цього агента.

Установіть nodeHost.skills.enabled: false на вузлі, щоб припинити публікацію. Оператори Gateway можуть ігнорувати навички з усіх сполучених вузлів за допомогою gateway.nodes.skills.enabled: false.

Стан ідентичності безголового вузла

Безголовий вузол зберігає три окремі записи стану:

• ~/.openclaw/state/openclaw.sqlite (node_host_config): ідентифікатор екземпляра клієнта, відображуване ім’я та метадані підключення до Gateway.
• ~/.openclaw/identity/device.json: підписана пара ключів пристрою та похідний криптографічний ідентифікатор пристрою.
• ~/.openclaw/identity/device-auth.json: токени автентифікації сполучених пристроїв, індексовані за криптографічним ідентифікатором пристрою та роллю.

Для підписаного вузла Gateway використовує криптографічний ідентифікатор пристрою для сполучення та маршрутизації вузла. Ідентифікатор екземпляра клієнта є лише метаданими підключення. Тому змінення --node-id або перенесення застарілого node.json не скидає сполучення. Див. Стан ідентичності та сполучення, щоб дізнатися про підтримувану процедуру відкликання й повторного сполучення та примітки щодо оновлення.

Додавання команд до списку дозволених

Схвалення виконання діють окремо для кожного хоста вузла. Додайте записи до списку дозволених із Gateway:

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

Схвалення зберігаються на хості вузла в ~/.openclaw/exec-approvals.json.

Спрямування виконання на вузол

Налаштуйте типові параметри (конфігурація Gateway):

openclaw config set tools.exec.host nodeopenclaw config set tools.exec.security allowlistopenclaw config set tools.exec.node "<id-or-name>"

Або для окремого сеансу:

/exec host=node security=allowlist node=<id-or-name>

Після налаштування будь-який виклик exec з host=node виконується на хості вузла (відповідно до списку дозволених і схвалень вузла).

host=auto не вибиратиме вузол неявно самостійно, але явний запит host=node для окремого виклику дозволений з auto. Щоб виконання на вузлі було типовим для сеансу, явно встановіть tools.exec.host=node або /exec host=node ....

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

• CLI хоста вузла
• Інструмент виконання
• Схвалення виконання

Локальний запуск моделей

Настільний або серверний вузол може надавати моделі з підтримкою чату із сервера Ollama, запущеного на цьому вузлі. Агенти використовують інструмент node_inference плагіна Ollama, щоб виявляти встановлені моделі та віддалено виконувати обмежений запит; Gateway не потребує прямого мережевого доступу до Ollama. Інструкції з налаштування, фільтрування моделей і команди безпосередньої перевірки див. у розділі Локальний запуск Ollama на вузлі.

Сеанси та транскрипти Codex

Офіційний плагін codex може надавати неархівовані сеанси Codex на безголовому хості вузла або нативному вузлі macOS. Реєстрація каталогу більше не залежить від supervision.enabled; цей параметр керує інструментами нагляду, доступними агенту. Установіть sessionCatalog.enabled: false у конфігурації плагіна Codex, щоб вимкнути команди каталогу оператора та каталогу сполучених вузлів, не вимикаючи провайдер або середовище. Плагін усе одно має бути активним на обох комп’ютерах, а параметр вузла залишається локальною згодою: увімкнення лише на Gateway не дає змоги читати стан Codex іншого комп’ютера.

Вузол оголошує версіоновані команди лише для читання codex.appServer.threads.list.v1 і codex.appServer.thread.turns.list.v1. Нативний хост вузла з доступним CLI Codex також оголошує codex.terminal.resume.v1. Схваліть оновлення сполучення вузла, коли ці команди з’являться вперше. Gateway викликає їх через звичайну політику вузлів плагіна й ізолює збої за хостами.

Рядки сполучених вузлів відображаються як група Codex на звичайній бічній панелі сеансів. Типово вибір рядка відкриває звичайну панель чату й читає збережений транскрипт через обмежені, пагіновані курсором виклики thread/turns/list з повною проєкцією елементів. Скористайтеся меню рядка, заголовком засобу перегляду або параметром Відкривати сеанси Codex/Claude у, щоб запустити codex resume <thread-id> у терміналі оператора на комп’ютері, якому належить сеанс. Шлях до термінала сполученого вузла — це ретранслятор PTY зі списку дозволених, яким керує плагін Codex, а не довільне виконання команд вузла.

Ретранслятор не надає повних контрактів продовження середовища OpenClaw і володіння архівом. Тому Продовжити та Архівувати недоступні для віддалених рядків. На комп’ютері Gateway збережені й неактивні рядки можуть запускати окрему гілку чату, зафіксовану на моделі. Будь-який із них можна архівувати лише після підтвердження оператором, що його не використовує жоден інший клієнт Codex; поточна активність збереженого рядка залишається невідомою. Активні рядки не можна розгалужувати або архівувати.

Інструкції з налаштування, пагінації, локального продовження та меж безпеки метаданих див. у розділі Нагляд за сеансами Codex.

Сеанси та транскрипти Claude

Вбудований плагін anthropic типово виявляє неархівовані сеанси Claude CLI та Claude Desktop на Gateway і сполучених вузлах. Установіть plugins.entries.anthropic.config.sessionCatalog.enabled: false, щоб вимкнути команди каталогу оператора та каталогу сполучених вузлів, не вимикаючи моделі Anthropic або бекенд Claude CLI. Віддалений вузол програми macOS оголошує anthropic.claude.sessions.list.v1 і anthropic.claude.sessions.read.v1, коли плагін Anthropic увімкнено та існує ~/.claude/projects/. Схваліть оновлення сполучення вузла, коли ці команди з’являться вперше.

Нативний хост вузла з доступним Claude CLI також оголошує anthropic.claude.terminal.resume.v1. Відповідні рядки CLI та Desktop можуть відкривати claude --resume <session-id> у терміналі оператора на хості, якому вони належать. Це перехоплення нативного сеансу; на відміну від прийняття OpenClaw, воно спочатку не створює відгалуження сеансу Claude.

Каталог поєднує дійсні записи індексу проєктів Claude CLI з обмеженим префіксом метаданих із поточних JSONL-файлів sdk-cli. Локальні метадані Claude Desktop надають назви Desktop і стан архівування. Метадані Desktop мають пріоритет, коли обидва джерела посилаються на той самий ідентифікатор сеансу Claude Code; транскрипти лише з CLI залишаються видимими, оскільки CLI не має прапорця архівування. Для читання транскриптів використовуються непрозорі курсори зсуву в байтах і обмежене зворотне читання файлів, тому вибір великого сеансу або завантаження старішої сторінки не зчитує всю історію JSONL в одну відповідь Gateway.

Команди списку й читання призначені лише для читання. Вони надають метадані каталогу та вміст транскрипту лише через загальні методи sessions.catalog.list і sessions.catalog.read автентифікованому підключенню оператора з operator.write. Локальний для Gateway рядок Claude CLI можна прийняти зі звичайного редактора чату: OpenClaw імпортує обмежену видиму історію, продовжує через --fork-session на першому кроці та залишає вихідний транскрипт незмінним.

Безголовий хост вузла може погодитися на такий самий процес продовження:

{  nodeHost: {    agentRuns: {      claude: { enabled: true },    },  },}

Вузол оголошує agent.cli.claude.run.v1, лише коли цей локальний параметр вузла ввімкнено й виконуваний файл claude доступний на цьому вузлі. Gateway не може ввімкнути його віддалено. Команда також проходить через наявну політику схвалення виконання вузла. Коли всі три команди Claude оголошені й дозволені політикою команд вузла Gateway, рядок Claude CLI на цьому вузлі можна продовжувати: OpenClaw імпортує обмежену історію, прив’язує прийнятий сеанс до вузла та його робочого каталогу, указаного в каталозі, і виконує там кожен одноразовий крок claude -p. Перший крок усе одно використовує --fork-session, зберігаючи вихідний транскрипт.

Кроки, виконані на вузлі, використовують типові параметри Claude цього вузла. У v1 вони не отримують конфігурацію MCP зворотного підключення Gateway або плагін навичок Gateway, не можуть повторно ініціалізуватися з транскрипту Gateway і відхиляють вкладення та зображення. Рядки Claude Desktop і вузли, які не оголошують команду запуску, залишаються доступними лише для перегляду. Вузол програми macOS поки не оголошує цю команду, тому його рядки залишаються доступними лише для перегляду.

Опис поведінки Control UI та джерел зберігання див. у розділі Anthropic: сеанси Claude на різних комп’ютерах.

Сеанси OpenCode і Pi

Вбудовані плагіни OpenCode і ACPX також виявляють нативні каталоги сеансів лише для читання на Gateway і сполучених вузлах. Вузол оголошує opencode.sessions.list.v1 / opencode.sessions.read.v1, коли встановлено CLI opencode, і acpx.pi.sessions.list.v1 / acpx.pi.sessions.read.v1, коли існує каталог сеансів Pi. Схваліть оновлення сполучення вузла, коли нові команди з’являться вперше. Коли відповідний CLI також доступний, вузол додає opencode.terminal.resume.v1 або acpx.pi.terminal.resume.v1; тоді наявне меню рядка й заголовок засобу перегляду можуть повторно відкрити вибраний сеанс у терміналі, якому він належить, за допомогою opencode --session <id> або pi --session <id>.

OpenCode виконує читання через офіційний інтерфейс JSON/експорту свого CLI. Pi читає документоване сховище сеансів JSONL, зокрема каталоги сеансів settings.json проєкту та глобальні каталоги, а також перевизначення PI_CODING_AGENT_DIR і PI_CODING_AGENT_SESSION_DIR. Обидва каталоги типово ввімкнені; вимкніть їх у Web UI в розділі Config > Plugins.

Відновлення в терміналі використовує збережений робочий каталог сеансу й той самий дуплексний ретранслятор PTY зі списку дозволених, що й Codex та Claude. Він не надає довільного виконання команд вузла.

Передавання файлів у термінал

У Control UI можна перетягувати файли у відкритий термінал сполученого вузла. Нативний хост вузла оголошує доступну лише адміністратору команду terminal.upload; схваліть оновлення сполучення, коли вона з’явиться вперше. Розмір кожного файла обмежено 16 MiB; файл поміщається в приватний тимчасовий каталог на цьому вузлі й повертається до термінала як шлях у лапках за правилами оболонки без виконання.

Вставлення шляхів підтримує PowerShell, cmd.exe і розпізнані POSIX-оболонки (sh, Bash, Dash, Ash, Ksh, Zsh і Fish), зокрема Git Bash у Windows. Інші перевизначення оболонки відхиляються, оскільки їхні правила взяття в лапки неможливо визначити безпечно; для нативних шляхів WSL запускайте хост вузла у WSL. Шляхи cmd.exe, що містять % або !, також відхиляються, оскільки ця оболонка розгортає ці символи навіть усередині подвійних лапок.

Виклик команд

Низькорівневий спосіб (необроблений RPC):

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

nodes invoke блокує system.run і system.run.prepare; ці команди виконуються лише через інструмент exec з host=node (див. вище). Для поширених процесів «надати агенту вкладення MEDIA» існують високорівневі допоміжні засоби (полотно, камера, екран, розташування — див. нижче).

Довготривалі потокові команди Node використовують додаткові події node.invoke.progress. Кожна подія містить ідентифікатор виклику, номер послідовності з відліком від нуля та обмежений фрагмент тексту UTF-8; Gateway упорядковує фрагменти перед передаванням викликачеві. Наявна відповідь node.invoke.result залишається єдиною завершальною відповіддю. Потокові викликачі можуть установити граничний термін бездіяльності, відлік якого починається з першої події прогресу та скидається після наступних подій прогресу, водночас зберігаючи окремий жорсткий тайм-аут виклику під час схвалення та виконання. Результат, жорсткий тайм-аут, тайм-аут бездіяльності та від'єднання Node видаляють увесь незавершений стан потоку. Скасування викликачем надсилає node.invoke.cancel; після цього хост Node завершує відповідне дерево процесів. Наявні команди запиту й відповіді не змінено.

Політика команд

Перед викликом команди Node мають пройти дві перевірки:

1. Node має оголосити команду у своїх автентифікованих метаданих підключення (connect.commands).
2. Список дозволених команд Gateway, сформований на основі платформи та схвалення, має містити оголошену команду.

Стандартні списки дозволених команд за платформами (до стандартних значень Plugin і перевизначень allowCommands/denyCommands):

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

Команди canvas.* (canvas.present, canvas.hide, canvas.navigate, canvas.eval, canvas.snapshot, canvas.a2ui.*) є стандартним значенням Plugin на iOS, Android, macOS, Windows, Linux і невідомих платформах. Node Linux оголошують їх лише за наявності локального сокета Canvas застосунку для настільних систем. Усі команди Canvas на iOS доступні лише на передньому плані.

talk.ptt.start, talk.ptt.stop, talk.ptt.cancel і talk.ptt.once за замовчуванням дозволені для будь-якого Node, який рекламує можливість talk або оголошує команди talk.*, незалежно від позначки платформи.

Команди хоста настільної системи (system.run, system.run.prepare, system.which, browser.proxy, mcp.tools.call.v1 і screen.snapshot у macOS/Windows) не входять до наведеної вище статичної таблиці стандартних значень платформ. Вони стають доступними після того, як оператор схвалить запит на сполучення, у якому їх оголошено; після цього набір схвалених команд Node зберігає їх під час повторного підключення.

Небезпечні команди або команди з істотним впливом на приватність усе одно потребують явного ввімкнення через gateway.nodes.allowCommands, навіть якщо Node оголошує їх: camera.snap, camera.clip, screen.record, computer.act, contacts.add, calendar.add, reminders.add, health.summary, sms.send, sms.search. gateway.nodes.denyCommands завжди має перевагу над стандартними значеннями й додатковими записами списку дозволених команд. Відомості про перевірку згоди на iPhone див. у розділі Зведення HealthKit, а про додаткові перевірки macOS, політики інструментів і активації введення на настільній системі — у розділі Керування комп'ютером.

Команди Node, що належать Plugin, можуть додавати політику викликів Node у Gateway. Ця політика виконується після перевірки списку дозволених команд і перед пересиланням до Node, тому необроблені node.invoke, допоміжні засоби CLI та спеціалізовані інструменти агента використовують ту саму межу дозволів Plugin. Небезпечні команди Node від Plugin усе одно потребують явного ввімкнення через gateway.nodes.allowCommands.

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

Конфігурація (openclaw.json)

Налаштування, пов'язані з Node, розміщено в gateway.nodes і tools.exec:

{  gateway: {    nodes: {      // Автоматично схвалювати перше сполучення Node з довірених мереж (список CIDR).      // Вимкнено, якщо значення не задано. Застосовується лише до перших запитів role:node      // без запитаних областей доступу; оновлення автоматично не схвалюються.      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],        // Автоматичне схвалення з перевіркою через SSH (за замовчуванням увімкнено). Схвалює перше        // сполучення Node за точного збігу ключа пристрою, зчитаного через SSH.        sshVerify: true,      },      // Довіряти видимим агенту інструментам Plugin, опублікованим сполученими Node (за замовчуванням: true).      pluginTools: {        enabled: true,      },      // Увімкнути небезпечні команди Node або команди з істотним впливом на приватність (camera.snap тощо).      allowCommands: ["camera.snap", "screen.record"],      // Блокувати точні назви команд, навіть якщо їх містять стандартні значення або allowCommands.      denyCommands: ["camera.clip"],    },  },  tools: {    exec: {      // Стандартний хост exec: "node" спрямовує всі виклики exec до сполученого Node.      host: "node",      // Режим безпеки для exec на Node: дозволяти лише схвалені команди або команди зі списку дозволених.      security: "allowlist",      // Закріпити exec за певним Node (ідентифікатором або назвою). Не вказуйте, щоб дозволити будь-який Node.      node: "build-node",    },  },}

Використовуйте точні назви команд Node. denyCommands вилучає команду, навіть якщо стандартне значення платформи або запис allowCommands інакше дозволяв би її. Сполучені Node за замовчуванням можуть публікувати видимі агенту дескриптори інструментів Plugin, але команда кожного дескриптора все одно має належати до схваленої поверхні команд Node. Установіть gateway.nodes.pluginTools.enabled: false, щоб ігнорувати всі такі дескриптори. Докладні відомості про поля сполучення Node у Gateway та політики команд див. у довіднику з конфігурації Gateway.

Перевизначення Node для exec окремого агента:

{  agents: {    list: [      {        id: "main",        tools: { exec: { node: "build-node" } },      },    ],  },}

Знімки екрана (знімки Canvas)

Якщо Node відображає Canvas (WebView), canvas.snapshot повертає { format, base64 }.

Допоміжний засіб CLI (записує в тимчасовий файл і виводить шлях до збереженого файла):

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format pngopenclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Елементи керування Canvas

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.comopenclaw nodes canvas hide --node <idOrNameOrIp>openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

Примітки:

• canvas present приймає URL-адреси або локальні шляхи до файлів (--target) на Node, що підтримують локальні шляхи, а також необов'язковий параметр --x/--y/--width/--height для позиціювання. Canvas у Linux приймає URL-адреси HTTP(S) або вбудований засіб відтворення A2UI.
• canvas eval приймає вбудований JS (--js) або позиційний аргумент.

A2UI (Canvas)

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonlopenclaw nodes canvas a2ui reset --node <idOrNameOrIp>

Примітки:

• Мобільні Node та Node для настільного Linux використовують вбудовану сторінку A2UI, що належить застосунку, для відтворення з підтримкою дій.
• Підтримується лише JSONL A2UI v0.8 (v0.9/createSurface відхиляється).
• iOS і Android відтворюють віддалені сторінки Canvas Gateway, але дії кнопок A2UI надсилаються лише з вбудованої сторінки A2UI, що належить застосунку. Сторінки A2UI HTTP/HTTPS, розміщені в Gateway, на цих мобільних клієнтах призначені лише для відтворення.
• macOS може надсилати дії з точної сторінки A2UI Gateway, обмеженої областю можливостей і вибраної застосунком. Інші сторінки HTTP/HTTPS залишаються доступними лише для відтворення.
• Linux надсилає дії лише з вбудованої сторінки A2UI. Інші сторінки HTTP/HTTPS залишаються доступними лише для відтворення, а безголовий Node Linux без застосунку для настільних систем не рекламує Canvas.

Фото та відео (камера Node)

Фото (jpg):

openclaw nodes camera list --node <idOrNameOrIp>openclaw nodes camera snap --node <idOrNameOrIp>            # за замовчуванням: обидва напрямки камер (2 рядки MEDIA)openclaw nodes camera snap --node <idOrNameOrIp> --facing frontopenclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

Відеокліпи (mp4):

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10sopenclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

Примітки:

• Для canvas.* і camera.* Node має перебувати на передньому плані (фонові виклики повертають NODE_BACKGROUND_UNAVAILABLE).
• Node обмежують тривалість кліпу, щоб розмір корисного навантаження base64 залишався прийнятним (точні обмеження для кожної платформи див. у розділі Знімання камерою). Інструмент агента nodes додатково обмежує запитане значення durationMs до 300000 (5 хвилин) перед пересиланням виклику; сам Node застосовує суворіше обмеження.
• Android за можливості запитує дозволи CAMERA/RECORD_AUDIO; у разі відмови в дозволах операція завершується помилкою *_PERMISSION_REQUIRED.

Записи екрана (Node)

Підтримувані Node надають screen.record (mp4). Приклад:

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

Примітки:

• Доступність screen.record залежить від платформи вузла.
• Інструмент агента nodes обмежує запитане значення durationMs до 300000 (5 хвилин); вузол може застосовувати суворіше обмеження для контролю розміру повернених даних.
• --no-audio вимикає захоплення звуку з мікрофона на підтримуваних платформах.
• Використовуйте --screen <index>, щоб вибрати дисплей, коли доступно кілька екранів (0 = основний).

Розташування (вузли)

Вузли надають location.get, коли в налаштуваннях увімкнено доступ до розташування.

Допоміжна команда CLI:

openclaw nodes location get --node <idOrNameOrIp>openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

Примітки:

• Доступ до розташування типово вимкнено.
• Режим "Always" потребує системного дозволу; фонове отримання даних виконується за можливості.
• Відповідь містить широту/довготу, точність (у метрах) і позначку часу.
• Повна структура параметрів і відповіді та коди помилок: Команда розташування.

SMS (вузли Android)

Вузли Android можуть надавати sms.send і sms.search, коли користувач надає дозвіл SMS, а пристрій підтримує телефонію. Обидві команди типово вважаються небезпечними: оператор Gateway також має додати їх до gateway.nodes.allowCommands, перш ніж їх можна буде викликати (див. Політика команд).

Щоб увімкнути пошук SMS лише для читання, явно додайте його до openclaw.json:

{  gateway: {    nodes: {      allowCommands: ["sms.search"],    },  },}

Додавайте sms.send окремо, лише якщо вузол також повинен мати змогу надсилати повідомлення. Дозвіл Android і авторизація команд Gateway незалежні; надання дозволу на телефоні не змінює політику Gateway.

Низькорівневий виклик:

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

Примітки:

• sms.search може бути оголошено до надання READ_SMS, щоб виклик міг повернути діагностику дозволу; для читання повідомлень цей дозвіл Android усе одно потрібен.
• Пристрої лише з Wi-Fi без підтримки телефонії не оголошуватимуть sms.send.
• Помилка requires explicit gateway.nodes.allowCommands opt-in означає, що телефон оголосив команду, але оператор Gateway її не авторизував.

Команди для роботи з даними пристрою та особистими даними

Вузли iOS і Android типово оголошують кілька команд читання даних (див. таблицю Політика команд); Android додатково надає ширший набір команд, доступ до яких регулюють власні налаштування застосунку.

Доступні групи:

• device.status, device.info — iOS, Android, Windows.
• device.permissions, device.health, device.apps — лише Android; device.apps потребує ввімкненого спільного доступу до встановлених застосунків у налаштуваннях Android і типово повертає застосунки, видимі в засобі запуску.
• notifications.list, notifications.actions — лише Android.
• photos.latest — iOS, Android.
• contacts.search — iOS, Android (типово лише читання); contacts.add є небезпечною командою та потребує gateway.nodes.allowCommands.
• calendar.events — iOS, Android (типово лише читання); calendar.add є небезпечною командою та потребує gateway.nodes.allowCommands.
• reminders.list — iOS, Android (типово лише читання); reminders.add є небезпечною командою та потребує gateway.nodes.allowCommands.
• callLog.search — лише Android.
• motion.activity, motion.pedometer — iOS, Android; доступ залежить від наявних датчиків.

Приклади викликів:

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'openclaw nodes invoke --node <idOrNameOrIp> --command device.apps --params '{"limit":10}'openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

Системні команди (хост вузла / вузол Mac)

Вузол macOS надає system.run, system.which, system.notify і system.execApprovals.get/set. Безінтерфейсний хост вузла надає system.run.prepare, system.run, system.which і system.execApprovals.get/set.

Приклади:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

Примітки:

• system.run повертає у корисному навантаженні стандартний вивід, стандартний вивід помилок і код завершення.
• Виконання команд оболонки тепер відбувається через інструмент exec із host=node; nodes залишається поверхнею прямого RPC для явних команд вузла.
• nodes invoke не надає system.run або system.run.prepare; вони залишаються доступними лише через шлях виконання.
• Шлях виконання готує канонічний systemRunPlan до схвалення. Після надання схвалення Gateway пересилає збережений план, а не змінені викликачем згодом поля команди, робочого каталогу чи сеансу.
• system.notify враховує стан дозволу на сповіщення в застосунку macOS; підтримує --priority <passive|active|timeSensitive> і --delivery <system|overlay|auto>.
• Для нерозпізнаних метаданих platform / deviceFamily вузла використовується консервативний типовий список дозволів, який не містить system.run і system.which. Якщо ці команди навмисно потрібні для невідомої платформи, явно додайте їх через gateway.nodes.allowCommands.
• system.run підтримує --cwd, --env KEY=VAL, --command-timeout і --needs-screen-recording.
• Для обгорток оболонки (bash|sh|zsh ... -c/-lc) значення --env, обмежені запитом, скорочуються до явного списку дозволів (TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR).
• Для рішень «завжди дозволяти» в режимі списку дозволів відомі обгортки диспетчеризації (env, flock, nice, nohup, stdbuf, timeout) зберігають шляхи до внутрішніх виконуваних файлів замість шляхів до обгорток. Якщо безпечне розгортання неможливе, запис до списку дозволів автоматично не зберігається.
• На хостах вузлів Windows у режимі списку дозволів запуски через обгортку оболонки за допомогою cmd.exe /c потребують схвалення (самого запису в списку дозволів недостатньо для автоматичного дозволу форми з обгорткою).
• Хости вузлів ігнорують перевизначення PATH у --env і перед виконанням команди вилучають великий підтримуваний набір змінних запуску інтерпретатора й оболонки (наприклад, NODE_OPTIONS, PYTHONPATH, BASH_ENV, DYLD_*, LD_*). Якщо потрібні додаткові записи PATH, налаштуйте середовище служби хоста вузла (або встановіть інструменти у стандартні розташування), а не передавайте PATH через --env.
• У режимі вузла macOS доступ до system.run регулюється схваленнями виконання в застосунку macOS (Settings → Exec approvals). Режими запиту, списку дозволів і повного доступу працюють так само, як на безінтерфейсному хості вузла; відхилені запити повертають SYSTEM_RUN_DENIED.
• На безінтерфейсному хості вузла доступ до system.run регулюється схваленнями виконання (~/.openclaw/exec-approvals.json); окремо для macOS див. змінні середовища маршрутизації хоста виконання в розділі Безінтерфейсний хост вузла нижче.

Прив’язування вузла виконання

Коли доступно кілька вузлів, виконання можна прив’язати до певного вузла. Це задає типовий вузол для exec host=node (його можна перевизначити для окремого агента).

Глобальне типове значення:

openclaw config set tools.exec.node "node-id-or-name"

Перевизначення для окремого агента:

openclaw config get agents.listopenclaw config set 'agents.list[0].tools.exec.node' "node-id-or-name"

Скасуйте значення, щоб дозволити будь-який вузол:

openclaw config unset tools.exec.nodeopenclaw config unset 'agents.list[0].tools.exec.node'

Мапа дозволів

Вузли можуть містити мапу permissions у node.list / node.describe, де ключами є назви дозволів (наприклад, screenRecording, accessibility, location), а значеннями — логічні значення (true = надано).

Безінтерфейсний хост вузла (кросплатформний)

OpenClaw може запускати безінтерфейсний хост вузла (без інтерфейсу користувача), який підключається до WebSocket Gateway і надає system.run / system.which. Це корисно в Linux/Windows або для запуску мінімального вузла поруч із сервером.

Запуск:

openclaw node run --host <gateway-host> --port 18789

Примітки:

• Сполучення все одно потрібне (Gateway покаже запит на сполучення пристрою).
• Метадані екземпляра клієнта, підписана ідентичність пристрою та автентифікація сполучення використовують окремі файли; див. Стан ідентичності безінтерфейсного вузла.
• Схвалення виконання застосовуються локально через ~/.openclaw/exec-approvals.json (див. Схвалення виконання).
• У macOS безінтерфейсний хост вузла типово виконує system.run локально. Установіть OPENCLAW_NODE_EXEC_HOST=app, щоб спрямовувати system.run через хост виконання супровідного застосунку; додайте OPENCLAW_NODE_EXEC_FALLBACK=0, щоб вимагати хост застосунку та безпечно завершувати роботу з помилкою, якщо він недоступний.
• Додайте --tls / --tls-fingerprint, коли WebSocket Gateway використовує TLS.

Режим вузла Mac

• Застосунок macOS у смузі меню підключається до сервера WebSocket Gateway як вузол (тому openclaw nodes … працює з цим Mac).
• У віддаленому режимі застосунок відкриває SSH-тунель для порту Gateway і підключається до localhost.