Перейти к основному содержанию

​
openclaw devices

Управляйте запросами на сопряжение устройств и токенами, ограниченными устройством.

​
Команды

​
openclaw devices list

Вывести ожидающие запросы на сопряжение и сопряженные устройства. 
openclaw devices list
openclaw devices list --json
В выводе ожидающего запроса запрошенный доступ показывается рядом с текущим одобренным доступом устройства, если устройство уже сопряжено. Это явно показывает повышение области доступа/роли, а не выглядит так, будто сопряжение было потеряно.

​
openclaw devices remove <deviceId>

Удалить одну запись сопряженного устройства. Когда вы аутентифицированы с помощью токена сопряженного устройства, вызывающие стороны без прав администратора могут удалять только запись своего устройства. Для удаления другого устройства требуется operator.admin. 
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json

​
openclaw devices clear --yes [--pending]

Массово очистить сопряженные устройства. 
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

​
openclaw devices approve [requestId] [--latest]

Одобрить ожидающий запрос на сопряжение устройства по точному requestId. Если requestId опущен или передан --latest, OpenClaw только выводит выбранный ожидающий запрос и завершает работу; повторно запустите одобрение с точным ID запроса после проверки деталей.
Если устройство повторяет сопряжение с измененными данными аутентификации (роль, области доступа или открытый ключ), OpenClaw заменяет предыдущую ожидающую запись и выдает новый requestId. Запустите openclaw devices list прямо перед одобрением, чтобы использовать текущий 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 approve
openclaw 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 (рекомендуется для скриптов).
Когда вы задаете --url, CLI не возвращается к учетным данным из конфигурации или окружения. Передайте --token или --password явно. Отсутствие явных учетных данных является ошибкой.

​
Примечания

  • Ротация токена возвращает новый токен (конфиденциальный). Обращайтесь с ним как с секретом.
  • Эти команды требуют область доступа 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.
  1. Подтвердите текущий источник токена Gateway:
openclaw config get gateway.auth.token
  1. Выведите сопряженные устройства и определите ID затронутого устройства:
openclaw devices list
  1. Ротируйте операторский токен для затронутого устройства:
openclaw devices rotate --device <deviceId> --role operator
  1. Если ротации недостаточно, удалите устаревшее сопряжение и одобрите снова:
openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>
  1. Повторите подключение клиента с текущим общим токеном/паролем.
Примечания:
  • Обычный порядок приоритета аутентификации при повторном подключении: сначала явный общий токен/пароль, затем явный deviceToken, затем сохраненный токен устройства, затем bootstrap-токен.
  • Доверенное восстановление AUTH_TOKEN_MISMATCH может временно отправить общий токен и сохраненный токен устройства вместе для одной ограниченной повторной попытки.
  • AUTH_SCOPE_MISMATCH означает, что токен устройства был распознан, но не несет запрошенный набор областей доступа; исправьте контракт одобрения сопряжения/областей доступа перед изменением общей аутентификации Gateway.
Связанные материалы:

​
Связанные материалы