Сопряжение Node

• Сопряжение устройства (роль node) ограничивает рукопожатие connect. См. Автоматическое одобрение устройства для доверенного CIDR ниже и Сопряжение каналов.
• Одобрение возможностей Node (node.pair.*) определяет, какие заявленные возможности/команды может предоставлять подключённый Node. Gateway является источником истины; интерфейсы (приложение macOS, Control UI) служат клиентскими оболочками, которые одобряют или отклоняют ожидающие запросы.

​

Как работает одобрение возможностей

1. Node подключается к WS Gateway (на этом этапе требуется сопряжение устройства).
2. Gateway сравнивает заявленный набор возможностей/команд с одобренным; новые или расширенные наборы сохраняются как ожидающий запрос в записи устройства и вызывают событие node.pair.requested.
3. Запрос одобряется или отклоняется (через CLI или интерфейс).
4. До одобрения команды Node остаются отфильтрованными; после одобрения заявленный набор становится доступен с учётом обычной политики команд.

​

Рабочий процесс CLI (подходит для среды без графического интерфейса)

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes remove --node <id|name|ip>
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

​

Поверхность API (протокол Gateway)

• node.pair.requested — вызывается при создании нового ожидающего запроса.
• node.pair.resolved — вызывается, когда запрос одобрен, отклонён или истёк.

• node.pair.list — выводит список ожидающих и сопряжённых Node (operator.pairing).
• node.pair.approve — одобряет ожидающий запрос.
• node.pair.reject — отклоняет ожидающий запрос.
• node.pair.remove — удаляет сопряжённый Node. Это отзывает роль node устройства в хранилище сопряжённых устройств, вместе с ней удаляет одобренную поверхность Node и делает недействительными/отключает сеансы этого устройства с ролью Node. Устройство со смешанными ролями (например, также имеющее operator) сохраняет свою строку и только теряет роль node; строка устройства только с ролью Node удаляется. Авторизация: operator.pairing может удалять строки Node, не относящиеся к оператору; вызывающей стороне с токеном устройства, отзывающей собственную роль Node на устройстве со смешанными ролями, дополнительно требуется operator.admin.
• node.rename — переименовывает отображаемое для оператора имя сопряжённого Node.

• При переподключении с неизменившейся поверхностью повторно используется ожидающий запрос; повторные запросы обновляют сохранённые метаданные Node и последний снимок заявленных команд из списка разрешённых для отображения оператору.
• Уровни областей действия оператора и проверки во время одобрения кратко описаны в разделе Области действия оператора.
• node.pair.approve использует заявленные в ожидающем запросе команды, чтобы требовать дополнительные области действия для одобрения:
  • запрос без команд: operator.pairing
  • запрос обычной команды: operator.pairing + operator.write
  • запрос с административно-чувствительными командами, содержащий system.run, system.run.prepare, system.which, browser.proxy, fs.listDir или system.execApprovals.get/set: operator.pairing + operator.admin

​

Ограничение команд Node (2026.3.31+)

• Node, которые ранее полагались только на сопряжение устройства для предоставления команд, теперь также должны выполнить сопряжение Node.
• Команды, поставленные в очередь до одобрения сопряжения, отбрасываются, а не откладываются.

​

Границы доверия событий Node (2026.3.31+)

​

Автоматическое одобрение устройства с проверкой по SSH (по умолчанию)

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

{
  gateway: {
    nodes: {
      pairing: {
        // Полное отключение:
        sshVerify: false,
        // ...или ограничение/настройка проверки:
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

​

Автоматическое одобрение (приложение macOS)

• запрос помечен как silent (шлюз помечает первую поверхность возможностей как тихую, если сопряжение устройства было одобрено неинтерактивно), и
• приложение может проверить SSH-подключение к хосту шлюза с использованием того же пользователя.

​

Автоматическое одобрение устройства для доверенного CIDR

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

• Отключено, если gateway.nodes.pairing.autoApproveCidrs не задан.
• Режима автоматического одобрения для всей LAN или частной сети не существует; автоматическое одобрение с проверкой по SSH (выше) требует криптографического совпадения ключа устройства, а не только нахождения в той же сети.
• Допускается только новый запрос сопряжения устройства role: node без запрошенных областей действия.
• Для клиентов оператора, браузера, Control UI и WebChat сохраняется ручное одобрение.
• Изменения роли, области действия, метаданных и открытого ключа требуют ручного одобрения.
• Пути заголовков доверенного прокси через loopback того же хоста не допускаются, поскольку этот путь может быть подделан локальными вызывающими сторонами.

​

Очистка заменённых тихих сопряжений

• Подходят только записи, последнее одобрение которых было локальным на том же хосте (silent) — как в качестве инициатора, так и в качестве цели. Сопряжения, подтверждённые через доверенный CIDR и SSH, охватывают разные хосты, где отображаемые метаданные не идентифицируют машину, поэтому они никогда не удаляются автоматически — для них используйте очистку в Control UI или openclaw nodes remove.
• Сопряжения, одобренные владельцем, а также сопряжения по QR-коду/коду настройки (первичной загрузки) никогда не удаляются автоматически. Записи, одобренные до появления данных о происхождении, остаются защищёнными даже после последующего автоматического повторного одобрения того же идентификатора устройства.
• Подключённые в данный момент устройства пропускаются, поэтому параллельные локальные сеансы с отдельными каталогами состояния сохраняют свои токены, пока активны. Записи, одобренные в течение последней минуты, также пропускаются, чтобы одновременные процедуры установления сопряжения не могли аннулировать друг друга до регистрации подключений.
• Затронутые клиенты по определению являются локальными, поэтому при следующем подключении они автоматически устанавливают сопряжение заново.

​

Автоматическое одобрение при обновлении метаданных

​

Вспомогательные средства сопряжения по QR-коду

​

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

​

Хранилище (локальное, закрытое)

• ~/.openclaw/state/openclaw.sqlite (сопряжённые устройства с аутентификацией устройств, одобренные поверхности Node, ожидающие запросы поверхностей, ожидающие запросы на сопряжение устройств и токены первичной загрузки)

• Токены устройств являются секретами; считайте базу данных состояния конфиденциальной.
• Для ротации токена устройства используются openclaw devices rotate / device.token.rotate.

​

Поведение транспорта

• Транспорт не сохраняет состояние; он не хранит данные о членстве.
• Если Gateway не подключён или сопряжение отключено, узлы не могут установить сопряжение.
• В удалённом режиме сопряжение выполняется с хранилищем удалённого Gateway.

​

Связанные разделы

• Сопряжение каналов
• CLI для узлов
• CLI для устройств