CLI commands
Устройства
openclaw devices
Управляйте запросами на сопряжение устройств и токенами, ограниченными устройством.
Команды
openclaw devices list
Вывести ожидающие запросы на сопряжение и сопряженные устройства.
openclaw devices listopenclaw devices list --jsonВ выводе ожидающего запроса запрошенный доступ показывается рядом с текущим одобренным доступом устройства, если устройство уже сопряжено. Это явно показывает повышение области доступа/роли, а не выглядит так, будто сопряжение было потеряно.
openclaw devices remove <deviceId>
Удалить одну запись сопряженного устройства.
Когда вы аутентифицированы с помощью токена сопряженного устройства, вызывающие
стороны без прав администратора могут удалять только запись своего
устройства. Для удаления другого устройства требуется operator.admin.
openclaw devices remove <deviceId>openclaw devices remove <deviceId> --jsonopenclaw devices clear --yes [--pending]
Массово очистить сопряженные устройства.
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --jsonopenclaw devices approve [requestId] [--latest]
Одобрить ожидающий запрос на сопряжение устройства по точному requestId. Если requestId
опущен или передан --latest, OpenClaw только выводит выбранный ожидающий
запрос и завершает работу; повторно запустите одобрение с точным ID запроса после проверки
деталей.
Если устройство уже сопряжено и запрашивает более широкие области доступа или более широкую роль,
OpenClaw сохраняет существующее одобрение и создает новый ожидающий запрос
на повышение. Проверьте столбцы Requested и Approved в openclaw devices list
или используйте openclaw devices approve --latest, чтобы предварительно просмотреть точное повышение перед
его одобрением.
Если Gateway явно настроен с
gateway.nodes.pairing.autoApproveCidrs, первые запросы role: node от
совпадающих IP-адресов клиентов могут быть одобрены до появления в этом списке. Эта политика
по умолчанию отключена и никогда не применяется к клиентам оператора/браузера или запросам
на повышение.
Для одобрения ролей устройств node или других неоператорских ролей требуется operator.admin.
operator.pairing достаточно только для одобрений операторских устройств, когда
запрошенные области доступа оператора остаются в пределах собственных областей доступа вызывающей стороны. См.
Области доступа оператора для проверок при одобрении.
openclaw devices approveopenclaw devices approve <requestId>openclaw devices approve --latestПервичное одобрение Paperclip / openclaw_gateway
Когда новый агент Paperclip впервые подключается через адаптер openclaw_gateway, Gateway может потребовать одноразовое одобрение сопряжения устройства, прежде чем запуски смогут успешно выполняться. Если Paperclip сообщает openclaw_gateway_pairing_required, одобрите ожидающее устройство и повторите попытку.
Для локальных Gateway предварительно просмотрите последний ожидающий запрос:
openclaw devices approve --latestПредварительный просмотр выводит точную команду openclaw devices approve <requestId>. Проверьте детали запроса, затем повторно запустите эту команду с ID запроса, чтобы одобрить его.
Для удаленных Gateway или явных учетных данных передавайте те же параметры при предварительном просмотре и одобрении:
openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>Чтобы не одобрять заново после перезапусков, храните постоянный ключ устройства в конфигурации адаптера Paperclip вместо генерации новой эфемерной идентичности при каждом запуске:
{ "adapterConfig": { "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>" }}Если одобрение продолжает завершаться ошибкой, сначала запустите openclaw devices list, чтобы подтвердить наличие ожидающего запроса.
openclaw devices reject <requestId>
Отклонить ожидающий запрос на сопряжение устройства.
openclaw devices reject <requestId>openclaw devices rotate --device <id> --role <role> [--scope <scope...>]
Ротировать токен устройства для конкретной роли (с необязательным обновлением областей доступа).
Целевая роль уже должна существовать в одобренном контракте сопряжения этого устройства;
ротация не может создать новую неодобренную роль.
Если вы опустите --scope, последующие повторные подключения с сохраненным ротированным токеном повторно используют
кэшированные одобренные области доступа этого токена. Если вы передадите явные значения --scope, они
станут сохраненным набором областей доступа для будущих повторных подключений с кэшированным токеном.
Вызывающие стороны сопряженного устройства без прав администратора могут ротировать только токен своего устройства.
Целевой набор областей доступа токена должен оставаться в пределах собственных операторских
областей доступа сеанса вызывающей стороны; ротация не может создать или сохранить более широкий операторский токен, чем тот,
который уже есть у вызывающей стороны.
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.writeВозвращает метаданные ротации в формате JSON. Если вызывающая сторона ротирует собственный токен, будучи аутентифицированной этим токеном устройства, ответ также включает заменяющий токен, чтобы клиент мог сохранить его перед повторным подключением. Общие/администраторские ротации не возвращают bearer-токен.
openclaw devices revoke --device <id> --role <role>
Отозвать токен устройства для конкретной роли.
Вызывающие стороны сопряженного устройства без прав администратора могут отзывать только токен своего устройства.
Для отзыва токена другого устройства требуется operator.admin.
Целевой набор областей доступа токена также должен помещаться в собственные
операторские области доступа сеанса вызывающей стороны; вызывающие стороны только с правом сопряжения не могут отзывать операторские токены admin/write.
openclaw devices revoke --device <deviceId> --role nodeВозвращает результат отзыва в формате JSON.
Общие параметры
--url <url>: WebSocket URL Gateway (по умолчаниюgateway.remote.url, если настроен).--token <token>: токен Gateway (если требуется).--password <password>: пароль Gateway (аутентификация по паролю).--timeout <ms>: тайм-аут RPC.--json: вывод JSON (рекомендуется для скриптов).
Примечания
- Ротация токена возвращает новый токен (конфиденциальный). Обращайтесь с ним как с секретом.
- Эти команды требуют область доступа
operator.pairing(илиoperator.admin). Некоторые одобрения также требуют, чтобы вызывающая сторона имела операторские области доступа, которые целевое устройство создало бы или унаследовало. Для неоператорских ролей устройств требуетсяoperator.admin; см. Области доступа оператора. gateway.nodes.pairing.autoApproveCidrs— это opt-in-политика Gateway только для нового сопряжения устройства node; она не меняет полномочия CLI на одобрение.- Ротация и отзыв токенов остаются внутри одобренного набора ролей сопряжения и одобренной базовой линии областей доступа для этого устройства. Случайная запись кэшированного токена не дает цель для управления токеном.
- Для сеансов с токеном сопряженного устройства управление между устройствами доступно только администраторам:
remove,rotateиrevokeограничены собственным устройством, если у вызывающей стороны нетoperator.admin. - Изменение токена также ограничено областью доступа вызывающей стороны: сеанс только с правом сопряжения не может
ротировать или отзывать токен, который сейчас несет
operator.adminилиoperator.write. devices clearнамеренно защищен флагом--yes.- Если область доступа сопряжения недоступна на local loopback (и явный
--urlне передан), list/approve может использовать локальный резервный путь сопряжения. devices approveтребует явный ID запроса перед созданием токенов; пропускrequestIdили передача--latestтолько предварительно показывает новейший ожидающий запрос.
Контрольный список восстановления при расхождении токенов
Используйте это, когда Control UI или другие клиенты продолжают завершаться ошибкой с AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH или AUTH_SCOPE_MISMATCH.
- Подтвердите текущий источник токена Gateway:
openclaw config get gateway.auth.token- Выведите сопряженные устройства и определите ID затронутого устройства:
openclaw devices list- Ротируйте операторский токен для затронутого устройства:
openclaw devices rotate --device <deviceId> --role operator- Если ротации недостаточно, удалите устаревшее сопряжение и одобрите снова:
openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>- Повторите подключение клиента с текущим общим токеном/паролем.
Примечания:
- Обычный порядок приоритета аутентификации при повторном подключении: сначала явный общий токен/пароль, затем явный
deviceToken, затем сохраненный токен устройства, затем bootstrap-токен. - Доверенное восстановление
AUTH_TOKEN_MISMATCHможет временно отправить общий токен и сохраненный токен устройства вместе для одной ограниченной повторной попытки. AUTH_SCOPE_MISMATCHозначает, что токен устройства был распознан, но не несет запрошенный набор областей доступа; исправьте контракт одобрения сопряжения/областей доступа перед изменением общей аутентификации Gateway.
Связанные материалы:
