Сопряжение

«Сопряжение» — это явный шаг подтверждения доступа в 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 telegramopenclaw 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

Поведение области действия учетных записей:

• Неосновные учетные записи читают и записывают только свой файл списка разрешений с областью действия.
• Учетная запись по умолчанию использует файл списка разрешений канала без области действия.

Считайте эти данные конфиденциальными (они ограничивают доступ к вашему ассистенту).

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 listopenclaw devices approve <requestId>openclaw devices reject <requestId>

Когда явное подтверждение отклонено из-за того, что подтверждающий сеанс сопряженного устройства был открыт только с областью действия сопряжения, CLI повторяет тот же запрос с operator.admin. Это позволяет существующему сопряженному устройству с правами администратора восстановить новое сопряжение Control UI/браузера без ручного редактирования devices/paired.json. Gateway по-прежнему проверяет повторное подключение; токены, которые не могут пройти аутентификацию с operator.admin, остаются заблокированными.

Если то же устройство повторяет попытку с другими данными аутентификации (например, другой ролью/областями действия/публичным ключом), предыдущий ожидающий запрос замещается и создается новый requestId.

Необязательное автоматическое подтверждение 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-узлам по-прежнему требуется сопряжение устройств.
• Запись сопряжения является долговечным источником истины для подтвержденных ролей. Активные токены устройств остаются ограниченными этим набором подтвержденных ролей; случайная запись токена вне подтвержденных ролей не создает новый доступ.

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

• Модель безопасности + prompt injection: Безопасность
• Безопасное обновление (запустите doctor): Обновление
• Конфигурации каналов:
  • Telegram: Telegram
  • WhatsApp: WhatsApp
  • Signal: Signal
  • iMessage: iMessage
  • Discord: Discord
  • Slack: Slack