English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Configuration

Сполучення

"Pairing" — це явний етап схвалення доступу в 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 telegram
openclaw pairing approve telegram <CODE>

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

Підтримувані канали: bluebubbles, 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 (перегляньте ID запитів, роль і області дії), потім схваліть.

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

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

Цей токен початкового завантаження має вбудований профіль початкового завантаження сполучення:

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

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

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

Схвалення пристрою Node

openclaw devices list
openclaw 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, browser, Control UI і WebChat все одно потребують ручного схвалення. Зміни ролі, області дії, метаданих і публічного ключа також потребують ручного схвалення.

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

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

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

Примітки

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

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