OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Сопряжение Node

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

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

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

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

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

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

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

bash
openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

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

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

События:

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

Методы:

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

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

Примечания:

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

Контроль доступа к командам узлов (2026.3.31+)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если беззвучное одобрение не удаётся, используется обычный запрос «Одобрить/Отклонить».

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

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

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

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

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

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

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

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

Границы:

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

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

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

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

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

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

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

При сопряжении Gateway считает подключение выполняемым через loopback только тогда, когда это подтверждают и необработанный сокет, и все данные вышестоящего прокси. Если запрос поступает через loopback, но содержит Forwarded, любой заголовок X-Forwarded-* или данные заголовка X-Real-IP, то эти данные перенаправленных заголовков исключают возможность считать подключение локальным через loopback, и процесс сопряжения требует явного одобрения вместо автоматического признания запроса подключением с того же хоста. Аналогичное правило для аутентификации оператора описано в разделе Аутентификация через доверенный прокси.

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

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

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

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

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

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

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

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

См. также

Was this useful?
On this page

On this page