openclaw devices

Zarządzaj żądaniami parowania urządzeń i tokenami o zakresie urządzenia.

Polecenia

openclaw devices list

Wyświetl oczekujące żądania parowania i sparowane urządzenia.

openclaw devices listopenclaw devices list --json

Dane wyjściowe oczekującego żądania pokazują żądany dostęp obok bieżącego zatwierdzonego dostępu urządzenia, gdy urządzenie jest już sparowane. Dzięki temu rozszerzenia zakresu/roli są jawne, a nie wyglądają tak, jakby parowanie zostało utracone.

openclaw devices remove <deviceId>

Usuń jeden wpis sparowanego urządzenia.

Gdy jesteś uwierzytelniony tokenem sparowanego urządzenia, wywołujący bez uprawnień administratora mogą usunąć tylko wpis własnego urządzenia. Usunięcie innego urządzenia wymaga operator.admin.

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

openclaw devices clear --yes [--pending]

Wyczyść sparowane urządzenia zbiorczo.

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

openclaw devices approve [requestId] [--latest]

Zatwierdź oczekujące żądanie parowania urządzenia według dokładnego requestId. Jeśli requestId zostanie pominięty lub przekazano --latest, OpenClaw tylko wypisuje wybrane oczekujące żądanie i kończy działanie; uruchom zatwierdzanie ponownie z dokładnym identyfikatorem żądania po zweryfikowaniu szczegółów.

Jeśli urządzenie jest już sparowane i prosi o szersze zakresy lub szerszą rolę, OpenClaw zachowuje istniejące zatwierdzenie i tworzy nowe oczekujące żądanie rozszerzenia uprawnień. Przejrzyj kolumny Requested i Approved w openclaw devices list albo użyj openclaw devices approve --latest, aby podejrzeć dokładne rozszerzenie przed jego zatwierdzeniem.

Jeśli Gateway jest jawnie skonfigurowany z gateway.nodes.pairing.autoApproveCidrs, pierwsze żądania role: node z pasujących adresów IP klientów mogą zostać zatwierdzone, zanim pojawią się na tej liście. Ta zasada jest domyślnie wyłączona i nigdy nie dotyczy klientów operatora/przeglądarki ani żądań rozszerzenia uprawnień.

Zatwierdzanie ról urządzeń typu node lub innych ról nieoperatorskich wymaga operator.admin. operator.pairing wystarcza do zatwierdzania urządzeń operatora tylko wtedy, gdy żądane zakresy operatora pozostają w zakresach samego wywołującego. Zobacz Zakresy operatora, aby poznać kontrole wykonywane przy zatwierdzaniu.

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

Zatwierdzanie pierwszego uruchomienia Paperclip / openclaw_gateway

Gdy nowy agent Paperclip łączy się po raz pierwszy przez adapter openclaw_gateway, Gateway może wymagać jednorazowego zatwierdzenia parowania urządzenia, zanim uruchomienia będą mogły się powieść. Jeśli Paperclip zgłasza openclaw_gateway_pairing_required, zatwierdź oczekujące urządzenie i spróbuj ponownie.

W przypadku lokalnych bram podejrzyj najnowsze oczekujące żądanie:

openclaw devices approve --latest

Podgląd wypisuje dokładne polecenie openclaw devices approve <requestId>. Zweryfikuj szczegóły żądania, a następnie uruchom to polecenie ponownie z identyfikatorem żądania, aby je zatwierdzić.

W przypadku zdalnych bram lub jawnych poświadczeń przekaż te same opcje podczas podglądu i zatwierdzania:

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

Aby uniknąć ponownego zatwierdzania po restartach, przechowuj trwały klucz urządzenia w konfiguracji adaptera Paperclip zamiast generować nową efemeryczną tożsamość przy każdym uruchomieniu:

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

Jeśli zatwierdzanie nadal się nie udaje, najpierw uruchom openclaw devices list, aby potwierdzić, że istnieje oczekujące żądanie.

openclaw devices reject <requestId>

Odrzuć oczekujące żądanie parowania urządzenia.

openclaw devices reject <requestId>

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

Rotuj token urządzenia dla określonej roli (opcjonalnie aktualizując zakresy). Rola docelowa musi już istnieć w zatwierdzonej umowie parowania tego urządzenia; rotacja nie może wystawić nowej, niezatwierdzonej roli. Jeśli pominiesz --scope, późniejsze ponowne połączenia z zapisanym rotowanym tokenem ponownie użyją zatwierdzonych zakresów zapisanych w pamięci podręcznej tego tokena. Jeśli przekażesz jawne wartości --scope, staną się one zapisanym zestawem zakresów dla przyszłych ponownych połączeń z tokenem z pamięci podręcznej. Wywołujący bez uprawnień administratora używający sparowanego urządzenia mogą rotować tylko token własnego urządzenia. Docelowy zestaw zakresów tokena musi pozostać w zakresach operatora własnej sesji wywołującego; rotacja nie może wystawić ani zachować szerszego tokena operatora niż ten, który wywołujący już ma.

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

Zwraca metadane rotacji jako JSON. Jeśli wywołujący rotuje własny token, będąc uwierzytelnionym tym tokenem urządzenia, odpowiedź zawiera również token zastępczy, aby klient mógł go utrwalić przed ponownym połączeniem. Rotacje współdzielone/administracyjne nie zwracają tokena okaziciela.

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

Unieważnij token urządzenia dla określonej roli.

Wywołujący bez uprawnień administratora używający sparowanego urządzenia mogą unieważnić tylko token własnego urządzenia. Unieważnienie tokena innego urządzenia wymaga operator.admin. Docelowy zestaw zakresów tokena musi również mieścić się w zakresach operatora własnej sesji wywołującego; wywołujący mający tylko parowanie nie mogą unieważniać tokenów operatora z uprawnieniami administratora/zapisu.

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

Zwraca wynik unieważnienia jako JSON.

Typowe opcje

• --url <url>: adres URL WebSocket Gateway (domyślnie gateway.remote.url, gdy jest skonfigurowany).
• --token <token>: token Gateway (jeśli wymagany).
• --password <password>: hasło Gateway (uwierzytelnianie hasłem).
• --timeout <ms>: limit czasu RPC.
• --json: dane wyjściowe JSON (zalecane do skryptów).

Uwagi

• Rotacja tokena zwraca nowy token (wrażliwy). Traktuj go jak sekret.
• Te polecenia wymagają zakresu operator.pairing (lub operator.admin). Niektóre zatwierdzenia wymagają również, aby wywołujący miał zakresy operatora, które urządzenie docelowe wystawiłoby lub odziedziczyło. Nieoperatorskie role urządzeń wymagają operator.admin; zobacz Zakresy operatora.
• gateway.nodes.pairing.autoApproveCidrs to opcjonalna zasada Gateway tylko dla świeżego parowania urządzeń node; nie zmienia uprawnień zatwierdzania w CLI.
• Rotacja i unieważnianie tokenów pozostają w obrębie zatwierdzonego zestawu ról parowania i zatwierdzonego bazowego zakresu dla tego urządzenia. Zabłąkany wpis tokena w pamięci podręcznej nie przyznaje celu zarządzania tokenami.
• W przypadku sesji tokenów sparowanego urządzenia zarządzanie między urządzeniami jest tylko dla administratora: remove, rotate i revoke dotyczą tylko własnego urządzenia, chyba że wywołujący ma operator.admin.
• Mutacja tokena jest również ograniczona zakresem wywołującego: sesja tylko z parowaniem nie może rotować ani unieważnić tokena, który obecnie przenosi operator.admin lub operator.write.
• devices clear jest celowo bramkowane przez --yes.
• Jeśli zakres parowania jest niedostępny w local loopback (i nie przekazano jawnego --url), list/approve może użyć lokalnej rezerwy parowania.
• devices approve wymaga jawnego identyfikatora żądania przed wystawieniem tokenów; pominięcie requestId lub przekazanie --latest tylko podgląda najnowsze oczekujące żądanie.

Lista kontrolna odzyskiwania po rozjechaniu tokenów

Użyj tego, gdy Control UI lub inni klienci nadal kończą się niepowodzeniem z AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH lub AUTH_SCOPE_MISMATCH.

1. Potwierdź bieżące źródło tokena gateway:

openclaw config get gateway.auth.token

2. Wyświetl sparowane urządzenia i zidentyfikuj identyfikator urządzenia, którego dotyczy problem:

openclaw devices list

3. Rotuj token operatora dla urządzenia, którego dotyczy problem:

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

4. Jeśli rotacja nie wystarczy, usuń nieaktualne parowanie i zatwierdź ponownie:

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

5. Ponów połączenie klienta z bieżącym współdzielonym tokenem/hasłem.

Uwagi:

• Normalny priorytet uwierzytelniania przy ponownym połączeniu to najpierw jawny współdzielony token/hasło, potem jawny deviceToken, potem zapisany token urządzenia, a na końcu token bootstrap.
• Zaufane odzyskiwanie po AUTH_TOKEN_MISMATCH może tymczasowo wysłać razem token współdzielony i zapisany token urządzenia dla jednej ograniczonej ponownej próby.
• AUTH_SCOPE_MISMATCH oznacza, że token urządzenia został rozpoznany, ale nie przenosi żądanego zestawu zakresów; napraw umowę zatwierdzenia parowania/zakresu przed zmianą współdzielonego uwierzytelniania gateway.

Powiązane:

• Rozwiązywanie problemów z uwierzytelnianiem dashboardu
• Rozwiązywanie problemów z Gateway

Powiązane

• Dokumentacja CLI
• Węzły