Сполучення

"Pairing" — це явний крок підтвердження доступу в OpenClaw. Він використовується у двох місцях:

1. DM pairing (кому дозволено спілкуватися з ботом)
2. Node pairing (яким пристроям/вузлам дозволено приєднуватися до мережі Gateway)

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

1) DM pairing (вхідний доступ до чату)

Коли канал налаштовано з політикою DM pairing, невідомі відправники отримують короткий код, а їхнє повідомлення не обробляється, доки ви не підтвердите доступ.

Типові політики DM задокументовано тут: Безпека

dmPolicy: "open" є публічною лише тоді, коли ефективний список дозволених DM містить "*". Налаштування й перевірка вимагають цей wildcard для публічно відкритих конфігурацій. Якщо наявний стан містить open із конкретними записами allowFrom, runtime усе одно допускає лише цих відправників, а підтвердження зі сховища pairing не розширюють доступ open.

Коди pairing:

• 8 символів, великі літери, без неоднозначних символів (0O1I).
• Закінчуються через 1 годину. Бот надсилає повідомлення pairing лише коли створюється новий запит (приблизно раз на годину для кожного відправника).
• Очікувані запити DM pairing типово обмежені 3 на канал; додаткові запити ігноруються, доки один не завершиться або не буде підтверджений.

Підтвердити відправника

openclaw pairing list telegramopenclaw pairing approve telegram <CODE>

Якщо власника команд ще не налаштовано, підтвердження коду DM pairing також ініціалізує commands.ownerAllowFrom для підтвердженого відправника, наприклад telegram:123456789. Це дає початковим налаштуванням явного власника для привілейованих команд і запитів підтвердження exec. Після появи власника наступні підтвердження pairing надають лише 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

Поведінка scoping облікового запису:

• Нетипові облікові записи читають/записують лише свій scoped-файл списку дозволених.
• Типовий обліковий запис використовує channel-scoped unscoped-файл списку дозволених.

Вважайте ці дані чутливими (вони контролюють доступ до вашого асистента).

2) Pairing пристроїв Node (iOS/Android/macOS/headless-вузли)

Вузли підключаються до Gateway як пристрої з role: node. Gateway створює запит pairing пристрою, який потрібно підтвердити.

Pairing з Control UI (рекомендовано)

Використайте вже підключену сесію Control UI з доступом operator.admin:

1. Відкрийте Control UI і виберіть Nodes.
2. У Devices натисніть Pair mobile device.
3. На телефоні відкрийте застосунок OpenClaw → Settings → Gateway.
4. Проскануйте QR-код або вставте код налаштування, а потім підключіться.

Офіційні застосунки OpenClaw для iOS і Android підтверджуються автоматично, коли їхні метадані setup-code збігаються. Якщо Devices показує очікуваний запит (наприклад, для неофіційного клієнта або невідповідних метаданих), перегляньте його роль і scopes перед підтвердженням.

Кнопка вимкнена, коли поточна сесія Control UI не має адміністраторського доступу. У такому разі використайте наведений нижче CLI-потік підтвердження з хоста Gateway.

Pairing через Telegram

Якщо ви використовуєте Plugin device-pair, можна виконати початковий pairing пристрою повністю з Telegram:

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

Код налаштування — це base64-закодоване JSON-навантаження, яке містить:

• url: URL WebSocket Gateway (ws://... або wss://...)
• bootstrapToken: короткочасний bootstrap-токен для одного пристрою, який використовується для початкового pairing-handshake

Цей bootstrap-токен несе вбудований bootstrap-профіль pairing:

• вбудований профіль налаштування дозволяє лише базовий fresh QR/setup-code: node плюс обмежену передачу operator
• переданий токен node лишається scopes: []
• переданий токен operator обмежено до operator.approvals, operator.read, operator.talk.secrets і operator.write
• operator.admin не надається через QR/setup-code bootstrap; для нього потрібен окремо підтверджений operator pairing або token flow
• подальша ротація/відкликання токенів лишається обмеженою як підтвердженим рольовим контрактом пристрою, так і operator scopes сесії виклику

Ставтеся до коду налаштування як до пароля, доки він чинний.

Для Tailscale, публічного або іншого віддаленого mobile pairing використовуйте Tailscale Serve/Funnel або інший wss:// URL Gateway. Plaintext-коди налаштування ws:// приймаються лише для loopback, приватних LAN-адрес, Bonjour-хостів .local і хоста Android emulator. Адреси Tailnet CGNAT, імена .ts.net і публічні хости все одно закриваються fail closed до видачі QR/setup-code.

Підтвердити пристрій Node

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

Коли явне підтвердження відхилено, бо сесію approving paired-device було відкрито лише з pairing-only scope, CLI повторює той самий запит із operator.admin. Це дає наявному paired-пристрою з можливостями admin відновити новий Control UI/browser pairing без ручного редагування devices/paired.json. Gateway усе одно перевіряє повторне підключення; токени, які не можуть автентифікуватися з operator.admin, залишаються заблокованими.

Якщо той самий пристрій повторює спробу з іншими даними автентифікації (наприклад іншими role/scopes/public key), попередній очікуваний запит замінюється й створюється новий requestId.

Необов’язкове авто-підтвердження Node для довірених CIDR

Pairing пристроїв типово лишається ручним. Для жорстко контрольованих мереж вузлів можна явно ввімкнути початкове авто-підтвердження Node з конкретними CIDR або точними IP:

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

Це застосовується лише до нових запитів pairing role: node без запитаних scopes. Operator, browser, Control UI і WebChat-клієнти все одно потребують ручного підтвердження. Зміни ролі, scope, метаданих і public-key також потребують ручного підтвердження.

Зберігання стану Node pairing

Зберігається в ~/.openclaw/devices/:

• pending.json (короткочасний; очікувані запити закінчуються)
• paired.json (paired-пристрої + токени)

Примітки

• Застарілий API node.pair.* (CLI: openclaw nodes pending|approve|reject|remove|rename) є окремим gateway-owned сховищем pairing. WS-вузли все одно потребують device pairing.
• Запис pairing є довговічним джерелом істини для підтверджених ролей. Активні device tokens лишаються обмеженими цим підтвердженим набором ролей; випадковий запис token поза підтвердженими ролями не створює нового доступу.

Пов’язані документи

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