Перейти к основному содержанию
«Сопряжение» — это явный шаг подтверждения доступа в OpenClaw. Оно используется в двух местах:
  1. DM-сопряжение (кому разрешено общаться с ботом)
  2. Сопряжение Node (каким устройствам/узлам разрешено присоединяться к сети Gateway)
Контекст безопасности: Безопасность

​
1) DM-сопряжение (доступ из входящего чата)

Когда канал настроен с DM-политикой pairing, неизвестные отправители получают короткий код, а их сообщение не обрабатывается, пока вы не подтвердите доступ. DM-политики по умолчанию описаны здесь: Безопасность dmPolicy: "open" является публичной только тогда, когда эффективный DM-список разрешений включает "*". Настройка и проверка требуют этот подстановочный знак для публично открытых конфигураций. Если существующее состояние содержит open с конкретными записями allowFrom, во время выполнения по-прежнему допускаются только эти отправители, а подтверждения из хранилища сопряжений не расширяют доступ open. Коды сопряжения:
  • 8 символов, верхний регистр, без неоднозначных символов (0O1I).
  • Истекают через 1 час. Бот отправляет сообщение о сопряжении только при создании нового запроса (примерно раз в час на отправителя).
  • Ожидающие DM-запросы сопряжения по умолчанию ограничены 3 на канал; дополнительные запросы игнорируются, пока один из них не истечет или не будет подтвержден.

​
Подтвердить отправителя

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
Если владелец команд еще не настроен, подтверждение DM-кода сопряжения также начально настраивает commands.ownerAllowFrom на подтвержденного отправителя, например telegram:123456789. Это дает первоначальным настройкам явного владельца для привилегированных команд и запросов подтверждения выполнения. После появления владельца последующие подтверждения сопряжения дают только DM-доступ; они не добавляют новых владельцев. Поддерживаемые каналы: discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.

​
Переиспользуемые группы отправителей

Используйте верхнеуровневые accessGroups, когда один и тот же набор доверенных отправителей должен применяться к нескольким каналам сообщений или одновременно к спискам разрешений DM и групп. Статические группы используют type: "message.senders" и указываются как accessGroup:<name> в списках разрешений каналов: 
{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}
Группы доступа подробно описаны здесь: Группы доступа

​
Где хранится состояние

Хранится в ~/.openclaw/credentials/:
  • Ожидающие запросы: <channel>-pairing.json
  • Хранилище подтвержденного списка разрешений:
    • Учетная запись по умолчанию: <channel>-allowFrom.json
    • Неосновная учетная запись: <channel>-<accountId>-allowFrom.json
Поведение области действия учетных записей:
  • Неосновные учетные записи читают и записывают только свой файл списка разрешений с областью действия.
  • Учетная запись по умолчанию использует файл списка разрешений канала без области действия.
Считайте эти данные конфиденциальными (они ограничивают доступ к вашему ассистенту).
Хранилище списка разрешений сопряжения предназначено для DM-доступа. Авторизация групп выполняется отдельно. Подтверждение DM-кода сопряжения не разрешает этому отправителю автоматически выполнять групповые команды или управлять ботом в группах. Начальная настройка первого владельца — это отдельное состояние конфигурации в commands.ownerAllowFrom, а доставка групповых чатов по-прежнему следует групповым спискам разрешений канала (например, groupAllowFrom, groups или переопределениям для отдельных групп или тем, в зависимости от канала).

​
2) Сопряжение устройств Node (iOS/Android/macOS/headless-узлы)

Узлы подключаются к Gateway как устройства с role: node. Gateway создает запрос сопряжения устройства, который необходимо подтвердить.

​
Сопряжение через Telegram (рекомендуется для iOS)

Если вы используете Plugin device-pair, вы можете выполнить первоначальное сопряжение устройства полностью из Telegram:
  1. В Telegram отправьте сообщение вашему боту: /pair
  2. Бот отвечает двумя сообщениями: сообщением с инструкцией и отдельным сообщением с кодом настройки (его удобно копировать и вставлять в Telegram).
  3. На телефоне откройте приложение OpenClaw iOS → Settings → Gateway.
  4. Отсканируйте QR-код или вставьте код настройки и подключитесь.
  5. Вернитесь в Telegram: /pair pending (просмотрите идентификаторы запросов, роль и области действия), затем подтвердите.
Код настройки — это JSON-полезная нагрузка в кодировке base64, которая содержит:
  • url: WebSocket URL Gateway (ws://... или wss://...)
  • bootstrapToken: короткоживущий bootstrap-токен для одного устройства, используемый для первоначального рукопожатия сопряжения
Этот bootstrap-токен несет встроенный bootstrap-профиль сопряжения:
  • встроенный профиль настройки разрешает только базовый вариант свежего QR/кода настройки: node плюс ограниченную передачу operator
  • переданный токен node остается scopes: []
  • переданный токен operator ограничен operator.approvals, operator.read и operator.write
  • operator.admin и operator.pairing не выдаются через bootstrap QR/кода настройки; для них требуется отдельное подтвержденное сопряжение оператора или поток токена
  • последующая ротация/отзыв токена остается ограниченной как подтвержденным контрактом роли устройства, так и operator-областями действия сеанса вызывающей стороны
Считайте код настройки паролем, пока он действителен. Для Tailscale, публичного или другого удаленного мобильного сопряжения используйте Tailscale Serve/Funnel или другой wss:// URL Gateway. Незашифрованные коды настройки ws:// принимаются только для loopback, частных LAN-адресов, хостов Bonjour .local и хоста эмулятора Android. Адреса Tailnet CGNAT, имена .ts.net и публичные хосты по-прежнему закрыто отклоняются до выдачи QR/кода настройки.

​
Подтвердить устройство Node

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
Когда явное подтверждение отклонено из-за того, что подтверждающий сеанс сопряженного устройства был открыт только с областью действия сопряжения, CLI повторяет тот же запрос с operator.admin. Это позволяет существующему сопряженному устройству с правами администратора восстановить новое сопряжение Control UI/браузера без ручного редактирования devices/paired.json. Gateway по-прежнему проверяет повторное подключение; токены, которые не могут пройти аутентификацию с operator.admin, остаются заблокированными. Если то же устройство повторяет попытку с другими данными аутентификации (например, другой ролью/областями действия/публичным ключом), предыдущий ожидающий запрос замещается и создается новый requestId.
Уже сопряженное устройство не получает более широкий доступ скрыто. Если оно переподключается, запрашивая больше областей действия или более широкую роль, OpenClaw сохраняет существующее подтверждение как есть и создает новый ожидающий запрос на повышение доступа. Используйте openclaw devices list, чтобы сравнить текущий подтвержденный доступ с новым запрошенным доступом перед подтверждением.

​
Необязательное автоматическое подтверждение Node по доверенным CIDR

Сопряжение устройств по умолчанию остается ручным. Для строго контролируемых сетей Node вы можете включить автоматическое подтверждение первого Node с явными CIDR или точными IP-адресами: 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
Это применяется только к новым запросам сопряжения role: node без запрошенных областей действия. Клиенты Operator, браузера, Control UI и WebChat по-прежнему требуют ручного подтверждения. Изменения роли, области действия, метаданных и публичного ключа по-прежнему требуют ручного подтверждения.

​
Хранилище состояния сопряжения Node

Хранится в ~/.openclaw/devices/:
  • pending.json (короткоживущее; ожидающие запросы истекают)
  • paired.json (сопряженные устройства + токены)

​
Примечания

  • Устаревший API node.pair.* (CLI: openclaw nodes pending|approve|reject|remove|rename) — это отдельное хранилище сопряжений, принадлежащее Gateway. WS-узлам по-прежнему требуется сопряжение устройств.
  • Запись сопряжения является долговечным источником истины для подтвержденных ролей. Активные токены устройств остаются ограниченными этим набором подтвержденных ролей; случайная запись токена вне подтвержденных ролей не создает новый доступ.

​
Связанные документы