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 на хосте Node. Поэтому запросы могут перейти в состояние одобренных вскоре после появления. Чтобы отключить проверку по 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. Если вызывающая сторона меняет собственный токен, будучи аутентифицированной с помощью этого токена устройства, ответ содержит новый токен, чтобы клиент мог сохранить его перед повторным подключением. При смене общих токенов или токенов администратором bearer-токен никогда не возвращается в ответе.

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.
• При смене токена возвращается новый токен (конфиденциальные данные) — обращайтесь с ним как с секретом.
• Если область доступа для сопряжения недоступна на локальном 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>

Чтобы не выполнять повторное одобрение после каждого перезапуска, настройте в Paperclip постоянный adapterConfig.devicePrivateKeyPem, вместо того чтобы позволять ему создавать новый временный идентификатор устройства при каждом запуске:

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

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

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

• Справочник CLI
• Узлы