---
read_when:
    - Реализация подтверждений сопряжения узлов без интерфейса macOS
    - Добавление сценариев CLI для одобрения удалённых узлов
    - Расширение протокола Gateway средствами управления узлами Node
summary: 'Подтверждение возможностей Node: как узлы получают доступ к выполнению команд после сопряжения устройства'
title: Сопряжение Node
x-i18n:
    generated_at: "2026-07-16T16:54:28Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 9e4221d7ad6aa6a9cd8ae33f2d4330c2aa49783340fcf7a657c20d6a94c126d9
    source_path: gateway/pairing.md
    workflow: 16
---

Сопряжение Node имеет два уровня, оба хранятся в записи сопряжённого устройства в
базе данных состояния SQLite Gateway:

- **Сопряжение устройства** (роль `node`) ограничивает рукопожатие `connect`. См.
  [Автоматическое одобрение устройства для доверенного CIDR](#trusted-cidr-device-auto-approval)
  ниже и [Сопряжение каналов](/ru/channels/pairing).
- **Одобрение возможностей Node** (`node.pair.*`) определяет, какие заявленные
  возможности/команды может предоставлять подключённый Node. Gateway является
  источником истины; интерфейсы (приложение macOS, Control UI) служат клиентскими оболочками, которые одобряют или
  отклоняют ожидающие запросы.

Прежнее отдельное хранилище сопряжений Node (`nodes/paired.json` с отдельным для каждого Node
токеном, исключённым из пути подключения в январе 2026 года) удалено: при запуске шлюзы однократно переносят
все оставшиеся строки в записи устройств и архивируют
устаревшие файлы с суффиксом `.migrated`. Поддержка устаревшего моста TCP
удалена.

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

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

Ожидающие запросы автоматически истекают через **5 минут после последней
повторной попытки Node** — активно переподключающийся Node поддерживает один ожидающий запрос,
а не создаёт новый запрос (и приглашение к одобрению) при каждой попытке.

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

```bash
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"
```

`nodes status` показывает сопряжённые/подключённые Node и их возможности.

## Поверхность 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.

Удалены в версии 2026.7: `node.pair.request` и `node.pair.verify`. Ожидающие
запросы создаются самим Gateway при подключении Node, а
отдельного токена для каждого Node, который они обслуживали, больше не существует; для аутентификации Node используется
токен сопряжения устройства.

Примечания:

- При переподключении с неизменившейся поверхностью повторно используется ожидающий запрос; повторные
  запросы обновляют сохранённые метаданные Node и последний снимок заявленных команд из списка разрешённых
  для отображения оператору.
- Уровни областей действия оператора и проверки во время одобрения кратко описаны в разделе
  [Области действия оператора](/ru/gateway/operator-scopes).
- `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`

<Warning>
Одобрение сопряжения Node фиксирует доверенную поверхность возможностей. Оно **не** закрепляет активную поверхность команд Node отдельно для каждого Node.

- Активные команды Node определяются тем, что Node заявляет при подключении, и фильтруются
  глобальной политикой команд Node шлюза (`gateway.nodes.allowCommands` и
  `denyCommands`).
- Политика разрешения и запроса `system.run` для каждого Node хранится на Node в
  `exec.approvals.node.*`, а не в записи сопряжения.

</Warning>

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

<Warning>
**Критическое изменение:** начиная с `2026.3.31`, команды Node отключены до одобрения сопряжения Node. Одного сопряжения устройства больше недостаточно для предоставления заявленных команд Node.
</Warning>

При первом подключении Node сопряжение запрашивается автоматически.
Пока этот запрос не одобрен, все ожидающие команды Node от этого Node
фильтруются и не выполняются. После одобрения сопряжения заявленные Node
команды становятся доступны с учётом обычной политики команд.

Это означает:

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

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

<Warning>
**Критическое изменение:** запуски, инициированные Node, теперь остаются в пределах сокращённой доверенной поверхности.
</Warning>

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

Долговременные обновления присутствия Node следуют той же границе идентификации: событие
`node.presence.alive` принимается только от аутентифицированных сеансов устройств Node
и обновляет метаданные сопряжения, только если идентичность устройства/Node
уже сопряжена. Самостоятельно заявленного значения `client.id` недостаточно для записи
состояния последнего присутствия.

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

Первичное сопряжение устройства `role: node` с частного адреса/адреса CGNAT
одобряется автоматически, когда шлюз может **подтвердить владение машиной по SSH**: он
подключается обратно к хосту сопряжения (`BatchMode`, `StrictHostKeyChecking=yes`),
запускает там `openclaw node identity --json` и одобряет запрос, только если удалённые
идентификатор устройства и открытый ключ точно совпадают с ожидающим запросом. Именно совпадение ключа
обеспечивает безопасность: одной доступности недостаточно для одобрения, поэтому соседи по NAT,
другие пользователи общего хоста и подмена в LAN переводятся в обычный
процесс с запросом подтверждения.

Включено по умолчанию. Условия срабатывания:

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

Пока выполняется проверка, клиенту Node предписывается продолжать повторные попытки
(`wait_then_retry`), а не приостанавливаться для ручного одобрения; если проверка
завершается неудачно, следующая попытка возвращается к обычному процессу подтверждения. Для неуспешно проверенных целей
действует короткая пауза (5 минут после несовпадения ключа).

Для одобренных устройств записывается `approvedVia: "ssh-verified"`, а их первая заявленная
поверхность возможностей одобряется на том же этапе — совпадение ключа уже подтверждает,
что Node работает под учётной записью оператора на принадлежащей ему машине, то есть подтверждает
то же утверждение, что и ручное одобрение возможностей. Последующие расширения поверхности по-прежнему
требуют подтверждения.

Усиление защиты или отключение:

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

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

Приложение macOS может попытаться выполнить **тихое одобрение** запросов возможностей Node,
если:

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

Если тихое одобрение завершается неудачно, используется обычный запрос Approve/Reject.

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

Сопряжение устройства по WS для `role: node` по умолчанию остаётся ручным. Для частных сетей Node,
в которых Gateway уже доверяет сетевому пути, операторы могут включить эту функцию,
явно указав CIDR или точные IP-адреса:

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

Граница безопасности:

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

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

При неинтерактивном одобрении его происхождение записывается в строке сопряжённого устройства:
одобрения локальной политикой того же хоста — как `silent`, одобрения Node для доверенного CIDR — как
`trusted-cidr`, одобрения Node с проверкой по SSH — как `ssh-verified`. Клиенты с эфемерным каталогом состояния (временные домашние каталоги,
контейнеры, отдельные песочницы для каждого запуска) создают новую пару ключей устройства при каждом запуске, и каждый
запуск тихо сопрягается заново как совершенно новое устройство — без очистки список сопряжённых устройств
увеличивается на одну устаревшую строку при каждом запуске.

Когда Gateway тихо одобряет **локальное** сопряжение устройства, он выводит из эксплуатации
более старые одобренные записи `silent`, принадлежащие тому же кластеру клиентов
(совпадают `clientId`, `clientMode` и отображаемое имя) и не подключённые в данный момент.
Локальные клиенты работают непосредственно на хосте шлюза, поэтому ключ кластера
не может совпасть с другой машиной. Токены выведенных из эксплуатации строк немедленно отзываются;
все соответствующие устаревшие записи сопряжения Node очищаются, а событие удаления `node.pair.resolved`
рассылается всем клиентам.

Границы:

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

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

Когда уже сопряжённое устройство переподключается, изменив только неконфиденциальные метаданные
(например, отображаемое имя или сведения о платформе клиента), OpenClaw рассматривает
это как `metadata-upgrade`. Область автоматического одобрения узка: оно применяется только
к доверенным локальным переподключениям не из браузера, которые уже подтвердили владение
локальными или общими учётными данными, включая переподключения нативного приложения на том же хосте после
изменения метаданных версии ОС. Клиенты браузера/Control UI и удалённые клиенты
по-прежнему используют явную процедуру повторного одобрения. Расширения области доступа (с чтения до
записи/администрирования) и изменения открытого ключа **не** допускают
автоматического одобрения при обновлении метаданных; они остаются явными запросами на повторное одобрение.

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

`/pair qr` отображает данные сопряжения как структурированный медиаконтент, чтобы мобильные и
браузерные клиенты могли сканировать его напрямую.

При удалении устройства также удаляются все устаревшие ожидающие запросы на сопряжение для этого
идентификатора устройства, поэтому `nodes pending` не показывает потерянные строки после отзыва.

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

При сопряжении Gateway считает подключение петлевым, только если с этим согласуются как исходный сокет,
так и все данные вышестоящего прокси. Если запрос поступает через петлевой интерфейс, но
содержит данные заголовка `Forwarded`, любого `X-Forwarded-*` или `X-Real-IP`,
эти данные перенаправленных заголовков делают утверждение о петлевой локальности недействительным, и
процедура сопряжения требует явного одобрения, а не автоматически считает
запрос подключением с того же хоста. Эквивалентное правило для
аутентификации оператора см. в разделе [Аутентификация доверенного прокси](/ru/gateway/trusted-proxy-auth).

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

Состояние сопряжения хранится в записях сопряжённых устройств в общей базе данных состояния SQLite
в каталоге состояния Gateway (по умолчанию `~/.openclaw`):

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

Если переопределить `OPENCLAW_STATE_DIR`, база данных переместится вместе с ним. При обновлении Gateway
с выпусков, использовавших хранилища JSON, они импортируются при запуске, а их архивы
`devices/*.json.migrated` и `nodes/*.json.migrated` сохраняются.

Примечания по безопасности:

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

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

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

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

- [Сопряжение каналов](/ru/channels/pairing)
- [CLI для узлов](/ru/cli/nodes)
- [CLI для устройств](/ru/cli/devices)