Узлы

​

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

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

• 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

​

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

​

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

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

​

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

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

​

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

# Терминал A (оставьте запущенным): перенаправление локального порта 18790 -> Gateway 127.0.0.1:18789
ssh -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 start
openclaw node restart

​

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

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

• --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-серверы на хосте узла

{
  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}",
          },
        },
      },
    },
  },
}

​

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

​

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

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

​

Добавление команд в список разрешённых

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

​

Направление выполнения на узел

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

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

• CLI хоста узла
• Инструмент выполнения
• Разрешения на выполнение

​

Локальный вывод модели

​

Сеансы и расшифровки Codex

​

Сеансы и расшифровки Claude

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

​

Сеансы OpenCode и Pi

​

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

​

Вызов команд

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

​

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

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

​

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

{
  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",
    },
  },
}

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

​

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

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

​

Элементы управления Canvas

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw 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.jsonl
openclaw 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.

​

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

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # по умолчанию: обе стороны (2 строки MEDIA)
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
openclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw 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.

​

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

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

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

​

Геопозиция (узлы)

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

• Геопозиция по умолчанию отключена.
• Для режима “Always” требуется системное разрешение; получение данных в фоновом режиме выполняется по мере возможности.
• Ответ содержит широту и долготу, точность (в метрах) и временную метку.
• Полная структура параметров и ответа, а также коды ошибок: команда геопозиции.

​

SMS (узлы Android)

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

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 не авторизовал её.

​

Команды для работы с данными устройства и личными данными

• 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)

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 в частности см. переменные окружения маршрутизации хоста выполнения в разделе Хост узла без графического интерфейса ниже.

​

Привязка узла выполнения

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

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

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

​

Карта разрешений

​

Хост узла без графического интерфейса (кроссплатформенный)

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.