Узлы

Узел — это вспомогательное устройство (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 необходимо обновить вне основного канала, прежде чем они смогут снова подключиться.

Прямой HTTPS-транспорт watchOS требует текущей версии протокола; обновите приложение часов одновременно с Gateway, прежде чем включать прямой режим.

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

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

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

• Запуски узла, требующие подтверждения, привязываются к точному контексту запроса. Путь выполнения подготавливает канонический systemRunPlan до подтверждения; после его получения Gateway перенаправляет сохранённый план, а не изменённые вызывающей стороной впоследствии поля команды/cwd/сеанса, и повторно проверяет рабочий каталог перед запуском.
• Для прямого выполнения файлов оболочки или среды выполнения 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> (по умолчанию: 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 (сохраняется в ~/.openclaw/node.json на узле вместе с идентификатором экземпляра клиента и метаданными подключения к 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 агента только пока этот узел остаётся подключённым. Имя каждого каталога Skills должно совпадать с полем frontmatter name, чтобы абстрактный указатель узла сопоставлялся с одной записью без добавления ещё одного поля протокола.

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

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

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

Состояние идентификации без графического интерфейса

Узел без графического интерфейса хранит три отдельных файла состояния:

• ~/.openclaw/node.json: устаревший идентификатор экземпляра клиента (хранится как nodeId), отображаемое имя и метаданные подключения к 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; этот параметр управляет доступностью инструментов наблюдения для агента. Плагин по-прежнему должен быть активен на обоих компьютерах, а настройка узла остаётся локальным согласием: включение только на Gateway не позволяет читать состояние Codex другого компьютера.

Узел объявляет версионированные команды только для чтения codex.appServer.threads.list.v1 и codex.appServer.thread.turns.list.v1. Одобрите обновление сопряжения узла при первом появлении этих команд. Gateway вызывает их через обычную политику узла плагина и изолирует сбои по хостам.

Строки сопряжённых узлов отображаются как группа Codex на обычной боковой панели сеансов. При выборе строки открывается обычная панель чата, которая читает сохранённую стенограмму через ограниченные вызовы thread/turns/list с постраничной навигацией по курсору и полной проекцией элементов. Транспорт вызова узла поддерживает только запросы и ответы и не может передавать потоковые реплики, события в реальном времени или одобрения, необходимые для продолжения нативной ветки через среду Codex. Поэтому для удалённых строк недоступны команды Продолжить и Архивировать. На компьютере Gateway для сохранённых и неактивных строк можно создать отдельную ветку чата, привязанную к модели. Любую из них можно архивировать только после подтверждения оператором, что её не использует другой клиент Codex; текущая активность сохранённой строки остаётся неизвестной. Активные строки нельзя разветвлять или архивировать.

Настройка, постраничная навигация, локальное продолжение и граница безопасности метаданных описаны в разделе Наблюдение за сеансами Codex.

Сеансы и стенограммы Claude

Встроенный плагин anthropic обнаруживает неархивированные сеансы Claude CLI и Claude Desktop на Gateway и сопряжённых узлах. В отличие от наблюдения за Codex, здесь не требуется отдельное согласие: удалённый узел приложения macOS объявляет anthropic.claude.sessions.list.v1 и anthropic.claude.sessions.read.v1, когда плагин Anthropic включён и существует ~/.claude/projects/. Одобрите обновление сопряжения узла при первом появлении этих команд.

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

Команды списка и чтения доступны только для чтения. Они предоставляют метаданные каталога и содержимое стенограмм только через универсальные методы sessions.catalog.list и sessions.catalog.read аутентифицированному подключению оператора с operator.write. Строку Claude CLI, локальную для Gateway, можно принять через обычное поле ввода чата: 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 или плагин Skills Gateway, не могут повторно инициализироваться из стенограммы Gateway и отклоняют вложения и изображения. Строки Claude Desktop и узлы, не объявляющие команду запуска, остаются доступными только для просмотра. Узел приложения macOS пока не объявляет эту команду, поэтому его строки также остаются доступными только для просмотра.

Поведение Control UI и источники хранения описаны в разделе Anthropic: сеансы Claude на разных компьютерах.

Вызов команд

Низкоуровневый вызов (необработанный 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); на iOS все они доступны только на переднем плане.

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: {      // Хост exec по умолчанию: "node" направляет все вызовы exec сопряжённому узлу.      host: "node",      // Режим безопасности для exec на узле: разрешать только одобренные команды или команды из списка разрешений.      security: "allowlist",      // Закрепить exec за определённым узлом (идентификатором или именем). Не указывайте, чтобы разрешить любой узел.      node: "build-node",    },  },}

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

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

{  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 eval принимает встроенный JavaScript (--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>

Примечания:

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

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

Фотографии (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 возвращает в полезной нагрузке стандартный вывод, стандартный поток ошибок и код завершения.
• Выполнение команд оболочки теперь осуществляется через инструмент exec с host=node; nodes остаётся поверхностью прямого RPC для явных команд узла.
• nodes invoke не предоставляет system.run или system.run.prepare; они остаются доступны только через путь exec.
• Путь exec подготавливает канонический 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 контролируется подтверждениями exec в приложении macOS (Settings → Exec approvals). Режимы запроса, списка разрешений и полного доступа работают так же, как на безголовом хосте узла; при отклонении запроса возвращается SYSTEM_RUN_DENIED.
• На безголовом хосте узла system.run контролируется подтверждениями exec (~/.openclaw/exec-approvals.json); для macOS в частности см. переменные окружения маршрутизации хоста exec в разделе Безголовый хост узла ниже.

Привязка узла exec

Если доступно несколько узлов, exec можно привязать к определённому узлу. Это задаёт узел по умолчанию для 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 отобразит запрос на сопряжение устройства).
• Метаданные экземпляра клиента, подписанное удостоверение устройства и данные аутентификации сопряжения хранятся в отдельных файлах; см. Состояние удостоверения безголового хоста.
• Подтверждения exec применяются локально через ~/.openclaw/exec-approvals.json (см. Подтверждения exec).
• В macOS безголовый хост узла по умолчанию выполняет system.run локально. Установите OPENCLAW_NODE_EXEC_HOST=app, чтобы направлять system.run через хост exec сопутствующего приложения; добавьте OPENCLAW_NODE_EXEC_FALLBACK=0, чтобы сделать хост приложения обязательным и при его недоступности безопасно завершать работу с отказом.
• Добавьте --tls / --tls-fingerprint, если WebSocket Gateway использует TLS.

Режим узла Mac

• Приложение строки меню macOS подключается к серверу WebSocket Gateway как узел (поэтому openclaw nodes … работает с этим Mac).
• В удалённом режиме приложение открывает SSH-туннель для порта Gateway и подключается к localhost.