Configuration

Сполучення

«Сполучення» — це явний етап схвалення доступу в OpenClaw. Він використовується у двох місцях:

Сполучення в приватних повідомленнях (хто може спілкуватися з ботом)
Сполучення Node (яким пристроям/вузлам дозволено приєднуватися до мережі Gateway)

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

1) Сполучення в приватних повідомленнях (доступ до вхідного чату)

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

Стандартні політики приватних повідомлень описано в розділі Безпека

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

Коди сполучення:

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

Схвалення відправника

bash

openclaw pairing list telegramopenclaw pairing approve telegram &lt;CODE&gt;

Додайте --notify до команди схвалення, щоб повідомити заявника в тому самому каналі. Для каналів із кількома обліковими записами вкажіть --account <id>.

Якщо власника команд ще не налаштовано, схвалення коду сполучення в приватних повідомленнях також установлює commands.ownerAllowFrom для схваленого відправника, наприклад telegram:123456789. Це надає новим конфігураціям явного власника для привілейованих команд і запитів на схвалення виконання. Після появи власника подальші схвалення сполучення надають лише доступ до приватних повідомлень; вони не додають нових власників.

Підтримувані канали (будь-який установлений Plugin каналу, що оголошує сполучення; зовнішні plugins, як-от 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>:

json5

{  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 конфіденційною, оскільки ці рядки керують доступом до вашого асистента.

Note

Сховище списку дозволених сполучень призначене для доступу до приватних повідомлень. Авторизація груп виконується окремо. Схвалення коду сполучення в приватних повідомленнях не надає цьому відправнику автоматичного дозволу виконувати групові команди або керувати ботом у групах. Початкове призначення першого власника є окремим станом конфігурації в commands.ownerAllowFrom, а доставлення повідомлень у груповому чаті й надалі визначається списками дозволених відправників групових повідомлень каналу (наприклад, groupAllowFrom, groups або перевизначеннями для окремих груп чи тем залежно від каналу).

2) Сполучення пристроїв Node (вузли iOS/Android/macOS/без інтерфейсу)

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

Сполучення через Control UI (рекомендовано)

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

Відкрийте Control UI і перейдіть до Settings → Devices.
На сторінці Devices натисніть Pair mobile device.
Залиште Full access (recommended) або виберіть Limited access, щоб виключити адміністративні засоби керування Gateway.
Натисніть Create setup code.
На телефоні відкрийте застосунок OpenClaw → Settings → Gateway.
Відскануйте QR-код або вставте код налаштування, а потім підключіться.

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

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

Сполучення через Telegram

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

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

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

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

bash

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

Якщо явне схвалення відхилено через те, що сеанс спареного пристрою, який виконує схвалення, відкрито з областю дії лише для сполучення, CLI повторює той самий запит із operator.admin. Це дає змогу наявному спареному пристрою з адміністративними можливостями відновити нове сполучення Control UI/браузера без ручного редагування сховища сполучень. Gateway усе одно перевіряє повторне підключення; токени, які не можуть пройти автентифікацію з operator.admin, залишаються заблокованими.

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

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

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

json5

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

Це застосовується лише до нових запитів на сполучення role: node без запитаних областей дії. Клієнти оператора, браузера, Control UI та WebChat усе одно потребують ручного схвалення. Зміни ролі, області дії, метаданих і відкритого ключа також потребують ручного схвалення.

Зберігання стану сполучення Node