Сопряжение

«Сопряжение» — это явный этап одобрения доступа в OpenClaw. Он используется в двух случаях:

1. Сопряжение в личных сообщениях (кому разрешено общаться с ботом)
2. Сопряжение Node (каким устройствам/узлам разрешено подключаться к сети Gateway)

Контекст безопасности: Безопасность

1) Сопряжение в личных сообщениях (доступ к входящим сообщениям)

Если для канала настроена политика личных сообщений pairing, неизвестные отправители получают короткий код, а их сообщение не обрабатывается, пока вы не одобрите доступ.

Политики личных сообщений по умолчанию описаны в разделе Безопасность.

dmPolicy: "open" является общедоступной только в том случае, если действующий список разрешённых отправителей личных сообщений содержит "*". Для настройки и проверки общедоступных конфигураций требуется этот подстановочный знак. Если существующее состояние содержит open с конкретными записями allowFrom, среда выполнения по-прежнему допускает только этих отправителей, а одобрения в хранилище сопряжений не расширяют доступ open.

Коды сопряжения:

• 8 символов, верхний регистр, без неоднозначных символов (0O1I).
• Срок действия истекает через 1 час. Бот отправляет сообщение о сопряжении только при создании нового запроса (примерно раз в час для каждого отправителя).
• Количество ожидающих запросов на сопряжение в личных сообщениях ограничено 3 на одну учётную запись канала; дополнительные запросы игнорируются, пока один из них не истечёт или не будет одобрен.

Одобрение отправителя

openclaw pairing list telegramopenclaw pairing approve telegram <CODE>

Добавьте --notify к команде одобрения, чтобы уведомить запрашивающего в том же канале. Для каналов с несколькими учётными записями используется --account <id>.

Если владелец команд ещё не настроен, одобрение кода сопряжения в личных сообщениях также назначает одобренного отправителя в commands.ownerAllowFrom, например telegram:123456789. Благодаря этому при первоначальной настройке явно определяется владелец привилегированных команд и запросов на одобрение выполнения. После назначения владельца последующие одобрения сопряжения предоставляют только доступ к личным сообщениям и не добавляют новых владельцев.

Поддерживаемые каналы (любой установленный плагин канала, объявляющий поддержку сопряжения; внешние плагины, например openclaw-weixin, могут добавлять другие): discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, signal, slack, sms, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.

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

Используйте верхнеуровневый параметр accessGroups, если один и тот же набор доверенных отправителей должен применяться к нескольким каналам сообщений или одновременно к спискам разрешённых отправителей для личных сообщений и групп.

Статические группы используют 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"] },  },}

Подробное описание групп доступа: Группы доступа

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

Оно хранится в общей базе данных состояния SQLite по адресу ~/.openclaw/state/openclaw.sqlite:

• ожидающие запросы в channel_pairing_requests
• одобренные отправители в channel_pairing_allow_entries

Принцип разделения по учётным записям:

• каждый запрос и одобренный отправитель идентифицируются по каналу и учётной записи
• среда выполнения читает только канонические строки SQLite и не объединяет данные из устаревших файлов

Старые версии Gateway записывали <channel>-pairing.json и <channel>-<accountId>-allowFrom.json в каталог ~/.openclaw/credentials/. Миграция при запуске и openclaw doctor --fix импортируют эти файлы в SQLite и удаляют каждый исходный файл после успешного импорта. Считайте базу данных SQLite конфиденциальной, поскольку эти строки определяют доступ к вашему ассистенту.

2) Сопряжение устройств Node (узлы iOS/Android/macOS/без графического интерфейса)

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

Сопряжение через Control UI (рекомендуется)

Используйте уже подключённый сеанс Control UI с доступом operator.admin:

1. Откройте Control UI и перейдите в Settings → Devices.
2. На странице Devices нажмите Pair mobile device.
3. Оставьте Full access (recommended) или выберите Limited access, чтобы исключить административные элементы управления Gateway.
4. Нажмите Create setup code.
5. На телефоне откройте приложение OpenClaw → Settings → Gateway.
6. Отсканируйте QR-код или вставьте код настройки, затем подключитесь.

Официальные приложения OpenClaw для iOS и Android одобряются автоматически, если их метаданные кода настройки совпадают. Если в разделе Pending approval отображается запрос (например, от неофициального клиента или с несовпадающими метаданными), перед одобрением проверьте его роль и области доступа.

Кнопка отключена, если текущий сеанс Control UI не имеет административного доступа. В таком случае используйте описанный ниже процесс одобрения через CLI на хосте Gateway.

Сопряжение через Telegram

Если вы используете плагин device-pair, первоначальное сопряжение устройства можно полностью выполнить через Telegram:

1. В Telegram отправьте своему боту сообщение: /pair
2. Бот ответит двумя сообщениями: сообщением с инструкцией и отдельным сообщением с кодом настройки (его удобно копировать и вставлять в Telegram).
3. На телефоне откройте приложение OpenClaw для iOS → Settings → Gateway.
4. Отсканируйте QR-код (/pair qr) или вставьте код настройки и подключитесь.
5. Официальное мобильное приложение подключается автоматически. Если /pair pending отображает запрос, перед одобрением проверьте его роль и области доступа.

Код настройки представляет собой JSON-объект в кодировке base64, содержащий:

• url: URL WebSocket для Gateway (ws://... или wss://...)
• urls: если доступны, упорядоченные маршруты LAN/Tailnet, которые может проверять мобильное приложение
• bootstrapToken: одноразовый начальный токен для первоначального рукопожатия сопряжения; Gateway аннулирует его через 10 минут

После завершения сопряжения выполните /pair cleanup, чтобы аннулировать неиспользованные коды настройки.

Этот начальный токен содержит встроенный профиль первоначальной настройки сопряжения:

• безопасная настройка wss:// (или loopback на том же хосте) по умолчанию предоставляет node и полный нативный мобильный доступ operator
• переданный токен node сохраняет значение scopes: []
• переданный по умолчанию токен operator включает operator.admin, operator.approvals, operator.read, operator.talk.secrets и operator.write
• режим Limited access в Control UI и openclaw qr --limited исключают operator.admin, сохраняя остальные области доступа оператора
• настройка через незашифрованный LAN ws:// автоматически использует тот же ограниченный профиль; настройте wss:// или Tailscale Serve и создайте новый код для полного доступа
• последующая ротация или отзыв токена по-прежнему ограничиваются как договором об одобренной роли устройства, так и областями доступа оператора в сеансе вызывающей стороны

Пока код настройки действителен, обращайтесь с ним как с паролем.

На страницах Settings → Gateway в приложениях для iOS и Android отображается уровень доступа Full или Limited. Чтобы повысить уровень доступа ограниченного телефона, сначала настройте безопасный маршрут wss:// или Tailscale Serve, затем создайте новый код настройки с полным доступом, отсканируйте или вставьте его на этой странице настроек и переподключитесь.

Для удалённого мобильного сопряжения через Tailscale, общедоступную сеть или другим способом используйте Tailscale Serve/Funnel или другой URL Gateway wss://. Коды настройки с незашифрованным ws:// принимаются только для loopback, частных адресов LAN, хостов Bonjour .local и хоста эмулятора Android. Маршруты с незашифрованным подключением вне loopback получают ограниченный доступ. Адреса CGNAT Tailnet, имена .ts.net и общедоступные хосты по-прежнему блокируются до выдачи QR-кода или кода настройки.

Для URL настройки gateway.bind=lan OpenClaw обнаруживает постоянные корневые HTTPS-адреса Tailscale Serve, которые проксируют loopback-порт активного Gateway, и предоставляет их вместе с маршрутом LAN. Команда настройки добавляет этот резервный вариант только для lan; custom и tailnet сохраняют явно указанные маршруты. Приложение для iOS проверяет указанные маршруты по порядку и сохраняет первую доступную конечную точку.

Одобрение устройства Node

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

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

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

Необязательное автоматическое одобрение узлов из доверенных CIDR

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

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

Это применяется только к новым запросам сопряжения role: node без запрошенных областей доступа. Клиенты оператора, браузера, Control UI и WebChat по-прежнему требуют ручного одобрения. Изменения роли, области доступа, метаданных и открытого ключа также требуют ручного одобрения.

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

Состояние хранится в общей базе данных SQLite по адресу ~/.openclaw/state/openclaw.sqlite:

• ожидающие запросы на сопряжение устройств (кратковременные; срок их действия истекает через 5 минут)
• сопряжённые устройства и токены

Старые версии Gateway хранили это состояние в ~/.openclaw/devices/*.json; эти файлы импортируются в SQLite при запуске Gateway и архивируются с суффиксом .migrated.

Примечания

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

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

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