openclaw devices

Керування запитами на сполучення пристроїв і токенами, прив’язаними до пристроїв.

Загальні параметри

• --url <url>: URL WebSocket для Gateway (типово використовується gateway.remote.url, якщо його налаштовано)
• --token <token>: токен Gateway (якщо потрібен)
• --password <password>: пароль Gateway (автентифікація паролем)
• --timeout <ms>: час очікування RPC
• --json: виведення у форматі JSON (рекомендовано для сценаріїв автоматизації)

Команди

openclaw devices list

Вивести список запитів на сполучення, що очікують розгляду, і сполучених пристроїв.

openclaw devices listopenclaw devices list --json

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

Для відображуваних імен сполучених пристроїв використовується такий порядок пріоритету: мітка оператора (operatorLabel з devices rename), потім клієнтське displayName, далі clientId, а потім deviceId.

openclaw devices approve [requestId] [--latest]

Схвалити запит на сполучення, що очікує розгляду, за точним requestId. Якщо не вказати requestId або передати --latest, команда лише покаже попередній перегляд найновішого запиту, що очікує розгляду, і завершиться (код 1); щоб схвалити запит, повторно виконайте команду з точним ідентифікатором запиту.

openclaw devices approveopenclaw devices approve <requestId>openclaw devices approve --latest

Поведінка під час схвалення:

• Якщо пристрій уже сполучено й він запитує ширші області дії або роль, OpenClaw зберігає наявне схвалення та створює новий запит на розширення, що очікує розгляду. Перед схваленням порівняйте Requested і Approved у виведенні openclaw devices list або перегляньте запит за допомогою --latest.
• Для схвалення ролі node або іншої ролі, що не є операторською, потрібна область дії operator.admin. Області дії operator.pairing достатньо для схвалення операторських пристроїв, але лише якщо запитані операторські області дії не виходять за межі власних областей дії викликувача. Див. Області дії оператора.
• Якщо налаштовано gateway.nodes.pairing.autoApproveCidrs, перші запити з role: node від відповідних IP-адрес клієнтів можуть бути автоматично схвалені ще до появи в цьому списку. Типово вимкнено; ніколи не застосовується до клієнтів-операторів, браузерних клієнтів або запитів на розширення.
• gateway.nodes.pairing.sshVerify (типово ввімкнено) автоматично схвалює перші запити з role: node, коли Gateway перевіряє ключ пристрою через SSH на хості вузла. Тому запити можуть перейти у схвалений стан невдовзі після появи. Щоб вимкнути перевірку через SSH, установіть sshVerify: false; цей параметр не залежить від autoApproveCidrs, тому для виключно ручного сполучення вимкніть також і його.

openclaw devices reject <requestId>

Відхилити запит на сполучення пристрою, що очікує розгляду.

openclaw devices reject <requestId>

openclaw devices remove <deviceId>

Видалити один запис сполученого пристрою.

openclaw devices remove <deviceId>openclaw devices remove <deviceId> --json

Викликувач, автентифікований за допомогою токена сполученого пристрою, може видалити запис лише власного пристрою. Для видалення іншого пристрою потрібна область дії operator.admin.

openclaw devices rename --device <id> --name <label>

Призначити мітку оператора сполученому пристрою. Мітки є станом на боці власника: вони зберігаються після відновлення сполучення та повторного схвалення ролей і не змінюють стабільний deviceId.

openclaw devices rename --device <deviceId> --name "Kitchen Mac"openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json

• Значення --name є обов’язковим, очищується від пробілів на початку й у кінці, не може бути порожнім і обмежене 64 символами.
• Інтерфейси відображення (список CLI, перелік у Control UI) надають перевагу мітці оператора над відображуваним іменем, яке повідомив клієнт.
• Викликувач зі сполученого пристрою без прав адміністратора може перейменувати лише власний пристрій. Для перейменування іншого пристрою потрібна область дії operator.admin.

openclaw devices clear --yes [--pending]

Масово видалити сполучені пристрої. Потребує підтвердження за допомогою --yes.

openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --json

Параметр --pending також відхиляє всі запити на сполучення, що очікують розгляду.

openclaw devices rotate --device <id> --role <role> [--scope <scope...>]

Оновити токен пристрою для ролі, за потреби змінивши його області дії.

openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

• Цільова роль уже має бути в схваленому договорі сполучення цього пристрою; оновлення не може створити нову несхвалену роль.
• Якщо не вказати --scope, під час наступних повторних підключень буде повторно використано кешовані схвалені області дії збереженого токена. Передавання явних значень --scope замінює збережений набір областей дії для майбутніх повторних підключень із кешованим токеном.
• Викликувач зі сполученого пристрою без прав адміністратора може оновити токен лише власного пристрою, а цільовий набір областей дії не повинен виходити за межі власних операторських областей дії викликувача; оновлення не може створити або зберегти токен із ширшими правами, ніж уже має викликувач.

Повертає метадані оновлення у форматі JSON. Якщо викликувач оновлює власний токен, будучи автентифікованим за допомогою токена цього пристрою, відповідь містить новий токен, щоб клієнт міг зберегти його перед повторним підключенням. Під час спільних або адміністраторських оновлень токен пред’явника ніколи не повертається у відповіді.

openclaw devices revoke --device <id> --role <role>

Відкликати токен пристрою для ролі.

openclaw devices revoke --device <deviceId> --role node

Викликувач зі сполученого пристрою без прав адміністратора може відкликати токен лише власного пристрою. Для відкликання токена іншого пристрою потрібна область дії operator.admin. Цільовий набір областей дії також не повинен виходити за межі власних операторських областей дії викликувача; викликувачі, що мають лише право на сполучення, не можуть відкликати адміністраторські або операторські токени з правом запису.

Примітки

• Для цих команд потрібна область дії operator.pairing (або operator.admin). Для ролей пристроїв, що не є операторськими, завжди потрібна область дії operator.admin; див. Області дії оператора.
• Оновлення та відкликання токенів залишаються в межах схваленого набору ролей сполучення пристрою та базового набору областей дії. Випадковий запис кешованого токена не створює цілі для керування токенами.
• Для сеансів із токеном сполученого пристрою міжпристроєве керування (remove, rename, rotate, revoke) обмежене власним пристроєм, якщо викликувач не має області дії operator.admin.
• Під час оновлення токена повертається новий токен (конфіденційний) — поводьтеся з ним як із секретом.
• Якщо область дії для сполучення недоступна через local loopback і явний параметр --url не передано, list/approve можуть використати локальний стан сполучення як резервний варіант.

Контрольний список відновлення після розбіжності токенів

Скористайтеся ним, якщо Control UI або інші клієнти й надалі завершують підключення з помилками AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH або AUTH_SCOPE_MISMATCH.

1. Перевірте поточне джерело токена Gateway:

   openclaw config get gateway.auth.token

2. Виведіть список сполучених пристроїв і визначте ідентифікатор проблемного пристрою:

   openclaw devices list

3. Оновіть операторський токен проблемного пристрою:

   openclaw devices rotate --device <deviceId> --role operator

4. Якщо оновлення недостатньо, видаліть застаріле сполучення та схваліть його знову:

   openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>

5. Повторіть спробу підключення клієнта з поточним спільним токеном або паролем.

Примітки:

• Звичайний порядок пріоритету автентифікації під час повторного підключення: спочатку явно вказаний спільний токен або пароль, потім явно вказаний deviceToken, далі збережений токен пристрою, а потім початковий токен.
• Надійне відновлення після AUTH_TOKEN_MISMATCH може тимчасово надіслати спільний токен і збережений токен пристрою разом для однієї обмеженої повторної спроби.
• AUTH_SCOPE_MISMATCH означає, що токен пристрою розпізнано, але він не містить запитаного набору областей дії; виправте договір схвалення сполучення й областей дії, перш ніж змінювати спільну автентифікацію Gateway.

Пов’язані матеріали:

• Усунення проблем з автентифікацією панелі керування
• Усунення проблем із Gateway

Схвалення першого запуску Paperclip / openclaw_gateway

Агенти Paperclip, які підключаються через адаптер openclaw_gateway, проходять те саме схвалення сполучення пристрою під час першого запуску, що й будь-який інший новий клієнт. Якщо Paperclip повідомляє про openclaw_gateway_pairing_required, схваліть пристрій, що очікує розгляду, і повторіть спробу.

openclaw devices approve --latest

Попередній перегляд виводить точну команду openclaw devices approve <requestId>; перевірте подробиці, а потім повторно виконайте цю команду з ідентифікатором запиту, щоб схвалити його. Для віддаленого Gateway або явно вказаних облікових даних передайте ті самі параметри під час попереднього перегляду та схвалення:

openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>

Щоб уникнути повторного схвалення після кожного перезапуску, налаштуйте постійний adapterConfig.devicePrivateKeyPem у Paperclip замість створення нової тимчасової ідентичності пристрою під час кожного запуску:

{  "adapterConfig": {    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"  }}

Якщо схвалення й надалі не вдається, спочатку виконайте openclaw devices list, щоб переконатися в наявності запиту, що очікує розгляду.

Пов’язані матеріали

• Довідник CLI
• Вузли