> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Сполучення

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

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

Контекст безпеки: [Безпека](/uk/gateway/security)

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

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

Типові політики DM задокументовано тут: [Безпека](/uk/gateway/security)

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

Коди pairing:

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw pairing list telegram
openclaw 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>` зі списків дозволених каналів:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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"] },
  },
}
```

Групи доступу докладно задокументовано тут: [Групи доступу](/uk/channels/access-groups)

### Де зберігається стан

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

* Очікувані запити: `<channel>-pairing.json`
* Сховище підтвердженого списку дозволених:
  * Типовий обліковий запис: `<channel>-allowFrom.json`
  * Нетиповий обліковий запис: `<channel>-<accountId>-allowFrom.json`

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

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

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

<Note>
  Сховище списку дозволених pairing призначене для DM-доступу. Групова авторизація є окремою.
  Підтвердження коду DM pairing не надає цьому відправнику автоматичний дозвіл виконувати групові
  команди або керувати ботом у групах. Початкова ініціалізація першого власника є окремим станом
  конфігурації в `commands.ownerAllowFrom`, а доставка групового чату й надалі дотримується
  групових списків дозволених каналу (наприклад `groupAllowFrom`, `groups` або override для групи
  чи теми залежно від каналу).
</Note>

## 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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw devices list
openclaw 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`.

<Note>
  Уже paired-пристрій не отримує ширший доступ непомітно. Якщо він повторно підключається й просить більше scopes або ширшу роль, OpenClaw залишає наявне підтвердження без змін і створює новий очікуваний запит на розширення. Використовуйте `openclaw devices list`, щоб порівняти поточний підтверджений доступ із новим запитаним доступом перед підтвердженням.
</Note>

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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: [Безпека](/uk/gateway/security)
* Безпечне оновлення (запустіть doctor): [Оновлення](/uk/install/updating)
* Конфігурації каналів:
  * Telegram: [Telegram](/uk/channels/telegram)
  * WhatsApp: [WhatsApp](/uk/channels/whatsapp)
  * Signal: [Signal](/uk/channels/signal)
  * iMessage: [iMessage](/uk/channels/imessage)
  * Discord: [Discord](/uk/channels/discord)
  * Slack: [Slack](/uk/channels/slack)