Узлы

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

Устаревший транспорт: Протокол Bridge (TCP JSONL; для текущих узлов приведён только в исторических целях).

macOS также может работать в режиме узла: приложение в строке меню подключается к WS-серверу Gateway как один узел (поэтому openclaw nodes … работает с этим Mac). Приложение добавляет нативные команды Canvas, камеры, экрана, уведомлений и управления компьютером в тот же набор команд хоста узла, который использует openclaw node run. Не запускайте второй CLI-узел на этом Mac: приложение запускает соответствующую среду хоста CLI-узла как внутренний рабочий процесс и остаётся единственным подключением к Gateway и единственным идентификатором узла.

Узлы — это периферийные устройства, а не шлюзы: они не запускают службу Gateway, а сообщения каналов (Telegram, WhatsApp и т. д.) поступают в Gateway, а не на узлы.

Инструкция по устранению неполадок: /nodes/troubleshooting

Сопряжение и состояние

Узлы используют сопряжение устройств. При подключении узел предоставляет подписанное удостоверение устройства; Gateway создаёт запрос на сопряжение устройства для role: node. Подтвердите его через CLI устройств (или пользовательский интерфейс). При настройке прямого подключения Apple Watch используется созданный администратором краткосрочный код настройки только для узла, чтобы разрешить фиксированный набор команд с низким уровнем риска; последующее расширение возможностей по-прежнему требует обычного подтверждения.

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

Ожидающие запросы на сопряжение истекают через 5 минут после последней повторной попытки устройства — устройство, которое продолжает переподключаться, поддерживает свой единственный ожидающий запрос (и requestId) активным, а не создаёт новое приглашение каждые несколько минут; полный жизненный цикл запроса и подтверждения описан в разделе Сопряжение узлов. Если узел повторяет попытку с изменёнными данными аутентификации (ролью, областями доступа или открытым ключом), предыдущий ожидающий запрос заменяется и создаётся новый requestId — клиенты получают событие device.pair.resolved для заменённого запроса, и перед подтверждением следует повторно выполнить openclaw devices list.

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

Расхождение версий и порядок обновления

WebSocket Gateway принимает аутентифицированные клиенты узлов в пределах окна протокола N-1. Поэтому текущий Gateway v4 принимает узлы v3, когда подключение объявляет одновременно role: "node" и client.mode: "node". Сеансы оператора и пользовательского интерфейса по-прежнему должны использовать текущую версию протокола.

Для поэтапного обновления парка сначала обновите Gateway, а затем каждый узел. Узел N-1 остаётся видимым и управляемым во время обновления; Gateway записывает legacy node protocol accepted с рекомендацией по обновлению. Требования к сопряжению, аутентификации устройств, спискам разрешённых команд и подтверждениям выполнения сохраняются. Возможности и команды, принадлежащие плагинам, остаются скрытыми, пока узел не обновится до текущей версии протокола. Узлы старше N-1 перед повторным подключением требуют обновления через отдельный канал.

Для прямого транспорта watchOS по HTTPS требуется текущая версия протокола; обновите приложение часов вместе с Gateway перед включением прямого режима.

Удалённый хост узла (system.run)

Используйте хост узла, когда Gateway работает на одном компьютере, а команды должны выполняться на другом. Модель по-прежнему взаимодействует со шлюзом; Gateway перенаправляет вызовы exec на хост узла, когда выбран host=node.

Примечание о подтверждениях:

• Запуски узла, требующие подтверждения, привязываются к точному контексту запроса. Путь выполнения подготавливает канонический systemRunPlan до подтверждения; после его получения Gateway пересылает сохранённый план, а не изменённые вызывающей стороной позднее поля команды, рабочего каталога или сеанса, и повторно проверяет рабочий каталог перед запуском.
• Для прямого выполнения файлов оболочкой или средой выполнения OpenClaw также по возможности привязывает один конкретный локальный файловый операнд и запрещает запуск, если этот файл изменился до выполнения.
• Если OpenClaw не может определить ровно один конкретный локальный файл для команды интерпретатора или среды выполнения, выполнение с подтверждением запрещается вместо имитации полного охвата среды выполнения. Для более широкой семантики интерпретатора используйте песочницу, отдельные хосты либо явно доверенный список разрешений или полный рабочий процесс.

Запуск хоста узла на переднем плане

На компьютере узла:

openclaw node run --host <gateway-host> --port 18789 --display-name "Сборочный узел"

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

Удалённый Gateway через SSH-туннель (привязка к loopback-интерфейсу)

Если Gateway привязан к loopback-интерфейсу (gateway.bind=loopback, значение по умолчанию в локальном режиме), удалённые хосты узлов не могут подключиться напрямую. Создайте SSH-туннель и направьте хост узла на локальный конец туннеля.

Пример (хост узла -> хост 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 "Сборочный узел"

Примечания:

• openclaw node run поддерживает аутентификацию по токену или паролю.
• Предпочтительны переменные среды: OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD.
• Резервные параметры конфигурации: gateway.auth.token / gateway.auth.password.
• В локальном режиме хост узла намеренно игнорирует gateway.remote.token / gateway.remote.password.
• В удалённом режиме gateway.remote.token / gateway.remote.password могут использоваться согласно правилам приоритета для удалённого режима.
• Если активные локальные SecretRef gateway.auth.* настроены, но не разрешаются, аутентификация хоста узла завершается отказом.
• При разрешении аутентификации хоста узла учитываются только переменные среды OPENCLAW_GATEWAY_*.

Запуск хоста узла как службы

openclaw node install --host <gateway-host> --port 18789 --display-name "Сборочный узел"openclaw node startopenclaw node restart

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

Сопряжение и присвоение имени

На хосте Gateway:

openclaw devices listopenclaw devices approve <requestId>openclaw nodes status

Если узел повторяет попытку с изменёнными данными аутентификации, повторно выполните 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-серверы на хосте узла

Настройте MCP-серверы в openclaw.json на компьютере узла, а не в 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}",          },        },      },    },  },}

Хост узла без графического интерфейса запускает эти серверы, получает список их инструментов и публикует дескрипторы после подключения. Вызовы инструментов возвращаются на этот узел через mcp.tools.call.v1; Gateway не требуется соответствующая конфигурация MCP или JS-плагин. MCP-серверы с OAuth не поддерживаются этим путём v1 на хосте узла.

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

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

Skills на хосте узла

Установите Skills в активный каталог Skills OpenClaw на компьютере узла, по умолчанию ~/.openclaw/skills. OPENCLAW_HOME, OPENCLAW_STATE_DIR и OPENCLAW_CONFIG_PATH изменяют этот активный профиль. Для Skills приоритет имеет OPENCLAW_STATE_DIR; в противном случае skills/ находится рядом с путём, который выводит openclaw config file. Хост узла без графического интерфейса публикует допустимые файлы SKILL.md после подключения, а Gateway добавляет их в снимки Skills агента только пока этот узел остаётся подключённым. Имя каждого каталога Skill должно соответствовать полю frontmatter name, чтобы абстрактный локатор узла сопоставлялся с одной записью без добавления ещё одного поля протокола.

Первоначальное сопряжение с ролью узла разрешает публикацию навыков. Добавление, удаление или изменение навыков не требует повторного сопряжения или изменения конфигурации 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. Нативный хост узла с доступным Codex CLI также объявляет codex.terminal.resume.v1. Одобрите обновление сопряжения узла, когда эти команды появятся впервые. Gateway вызывает их через обычную политику узлов плагина и изолирует сбои по хостам.

Строки сопряжённых узлов отображаются как группа Codex на обычной боковой панели сеансов. По умолчанию выбор строки открывает обычную панель чата и читает сохранённую расшифровку посредством ограниченных, разбитых на страницы с помощью курсора вызовов thread/turns/list с полной проекцией элементов. Используйте меню строки, заголовок средства просмотра или настройку Open Codex/Claude sessions in, чтобы запустить codex resume <thread-id> в терминале оператора на компьютере, которому принадлежит сеанс. Путь к терминалу сопряжённого узла представляет собой ретранслятор PTY из списка разрешённых, которым управляет плагин Codex, а не механизм выполнения произвольных команд узла.

Ретранслятор не предоставляет полные контракты продолжения среды выполнения OpenClaw и владения архивом. Поэтому Continue и Archive недоступны для удалённых строк. На компьютере 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. Оба каталога включены по умолчанию; отключите их в веб-интерфейсе в разделе Config > Plugins.

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

Отправка файлов в терминал

Control UI позволяет перетаскивать файлы в открытый терминал сопряжённого узла. Нативный хост узла объявляет доступную только администраторам команду terminal.upload; одобрите обновление сопряжения при её первом появлении. Размер каждого файла ограничен 16 МиБ; файл помещается в закрытый временный каталог на этом узле и возвращается в терминал как путь, экранированный для оболочки, без его выполнения.

Вставка пути поддерживает 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.invoke.progress. Каждое событие содержит идентификатор вызова, порядковый номер с нуля и ограниченный фрагмент текста в UTF-8; Gateway упорядочивает фрагменты перед их доставкой вызывающей стороне. Существующий node.invoke.result остаётся единственным завершающим ответом. Потоковые вызывающие стороны могут задать крайний срок бездействия, отсчёт которого начинается с первого события прогресса и сбрасывается после последующих событий прогресса, при этом отдельный жёсткий тайм-аут вызова продолжает действовать во время подтверждения и выполнения. Результат, жёсткий тайм-аут, тайм-аут бездействия и отключение узла удаляют всё ожидающее потоковое состояние. Отмена со стороны вызывающей стороны порождает node.invoke.cancel; затем хост узла завершает соответствующее дерево процессов. Существующие команды запросов и ответов не изменены.

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

Перед вызовом команды узла должны пройти две проверки:

1. Узел должен объявить команду в метаданных своего аутентифицированного подключения (connect.commands).
2. Список разрешённых команд Gateway, определяемый платформой и подтверждением, должен включать объявленную команду.

Списки разрешённых по умолчанию для каждой платформы (до применения настроек плагинов по умолчанию и переопределений allowCommands/denyCommands):

Эти строки описывают верхнюю границу политики Gateway, а не команды, реализованные каждым приложением узла. Команда доступна, только если подключённый узел также объявляет её. В частности, текущее приложение macOS не объявляет семейства команд для устройств и персональных данных, перечисленные в строке политики macOS.

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

talk.ptt.start, talk.ptt.stop, talk.ptt.cancel и talk.ptt.once по умолчанию разрешены для любого узла, который сообщает о возможности talk или объявляет команды talk.*, независимо от обозначения платформы.

Команды хоста настольной системы (system.run, system.run.prepare, system.which, browser.proxy, mcp.tools.call.v1 и screen.snapshot на macOS/Windows) не входят в приведённую выше статическую таблицу платформенных настроек по умолчанию. Они становятся доступными после того, как оператор подтверждает запрос на сопряжение, в котором они объявлены; после этого набор подтверждённых команд узла сохраняет их при повторном подключении.

Опасные команды или команды, существенно затрагивающие конфиденциальность, по-прежнему требуют явного включения через gateway.nodes.allowCommands, даже если узел объявляет их: 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, политики инструментов и активации для ввода на настольной системе — в разделе Управление компьютером.

Команды узлов, принадлежащие плагинам, могут добавлять политику Gateway для вызова узла. Эта политика выполняется после проверки списка разрешённых команд и перед передачей вызова узлу, поэтому необработанные node.invoke, вспомогательные средства CLI и специализированные инструменты агента используют одну и ту же границу разрешений плагина. Опасные команды узлов плагина по-прежнему требуют явного включения через gateway.nodes.allowCommands.

После изменения узлом списка объявленных команд отклоните прежнее сопряжение устройства и подтвердите новый запрос, чтобы Gateway сохранил обновлённый снимок команд.

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

Настройки, связанные с узлами, находятся в разделах gateway.nodes и tools.exec:

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

Используйте точные имена команд узлов. denyCommands удаляет команду, даже если настройка платформы по умолчанию или запись allowCommands в противном случае разрешала бы её. Сопряжённые узлы по умолчанию могут публиковать видимые агенту дескрипторы инструментов плагинов, однако команда каждого дескриптора всё равно должна входить в подтверждённую поверхность команд узла. Установите gateway.nodes.pluginTools.enabled: false, чтобы игнорировать все такие дескрипторы. Подробные сведения о полях сопряжения узлов Gateway и политики команд см. в справочнике по конфигурации Gateway.

Переопределение узла выполнения для отдельного агента:

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

Снимки экрана (снимки Canvas)

Если узел отображает 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) на узлах, поддерживающих локальные пути, а также необязательный --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>

Примечания:

• Мобильные узлы и настольные узлы 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 предназначены только для отображения, а узел Linux без графического интерфейса и настольного приложения не сообщает о Canvas.

Фотографии и видео (камера узла)

Фотографии (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_BACKGROUND_UNAVAILABLE).
• Узлы ограничивают длительность клипа, чтобы размер полезной нагрузки base64 оставался приемлемым (точные ограничения для каждой платформы см. в разделе Съёмка с камеры). Инструмент агента nodes дополнительно ограничивает запрошенное значение durationMs до 300000 (5 минут) перед передачей вызова; сам узел применяет более строгое ограничение.
• Android по возможности запрашивает разрешения CAMERA/RECORD_AUDIO; при отказе в разрешении операция завершается ошибкой *_PERMISSION_REQUIRED.

Запись экрана (узлы)

Поддерживаемые узлы предоставляют 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 возвращает в полезной нагрузке stdout, stderr и код завершения.
• Выполнение команд оболочки теперь осуществляется через инструмент exec с host=node; nodes остаётся поверхностью прямого RPC для явных команд узла.
• nodes invoke не предоставляет system.run или system.run.prepare; они остаются доступными только через путь выполнения.
• Перед подтверждением путь выполнения подготавливает канонический systemRunPlan. После предоставления подтверждения Gateway пересылает сохранённый план, а не изменённые вызывающей стороной позднее поля команды, cwd или сеанса.
• 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). Режимы Ask, allowlist и full работают так же, как на хосте узла без графического интерфейса; отклонённые запросы возвращают 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.