openclaw devices

Zarządzaj żądaniami parowania urządzeń i tokenami przypisanymi do urządzeń.

Typowe opcje

• --url <url>: adres URL WebSocket Gateway (domyślnie gateway.remote.url, jeśli skonfigurowano)
• --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 w skryptach)

Polecenia

openclaw devices list

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

openclaw devices listopenclaw devices list --json

W przypadku oczekującego żądania dotyczącego już sparowanego urządzenia dane wyjściowe pokazują żądany dostęp obok obecnie zatwierdzonego dostępu urządzenia, dzięki czemu rozszerzenia zakresu lub roli są widoczne i nie wyglądają jak utracone parowanie.

Nazwy wyświetlane sparowanych urządzeń są wybierane według następującej kolejności: etykieta operatora (operatorLabel z devices rename), następnie displayName klienta, potem clientId, a na końcu deviceId.

openclaw devices approve [requestId] [--latest]

Zatwierdź oczekujące żądanie parowania na podstawie dokładnego requestId. Pominięcie requestId lub przekazanie --latest powoduje tylko wyświetlenie podglądu najnowszego oczekującego żądania i zakończenie działania (kod 1); aby zatwierdzić żądanie, uruchom polecenie ponownie z dokładnym identyfikatorem żądania.

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

Zasady zatwierdzania:

• Jeśli urządzenie jest już sparowane i żąda szerszych zakresów lub innej roli, OpenClaw zachowuje dotychczasowe zatwierdzenie i tworzy nowe oczekujące żądanie rozszerzenia uprawnień. Przed zatwierdzeniem porównaj Requested z Approved w openclaw devices list lub wyświetl podgląd za pomocą --latest.
• Zatwierdzenie roli node lub innej roli niebędącej operatorem wymaga operator.admin. operator.pairing wystarcza do zatwierdzania urządzeń operatora, ale tylko wtedy, gdy żądane zakresy operatora mieszczą się w zakresach własnych wywołującego. Zobacz Zakresy operatora.
• Jeśli skonfigurowano gateway.nodes.pairing.autoApproveCidrs, pierwsze żądania z role: node pochodzące z pasujących adresów IP klientów mogą zostać automatycznie zatwierdzone, zanim pojawią się na tej liście. Funkcja jest domyślnie wyłączona; nigdy nie dotyczy klientów operatora/przeglądarki ani żądań rozszerzenia uprawnień.
• gateway.nodes.pairing.sshVerify (domyślnie włączone) automatycznie zatwierdza pierwsze żądania z role: node, gdy Gateway zweryfikuje klucz urządzenia przez SSH na hoście węzła. Dlatego żądania mogą zostać zatwierdzone krótko po pojawieniu się. Ustaw sshVerify: false, aby wyłączyć weryfikację SSH; jest ona niezależna od autoApproveCidrs, więc wyłącz również tę opcję, jeśli parowanie ma odbywać się wyłącznie ręcznie.

openclaw devices reject <requestId>

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

openclaw devices reject <requestId>

openclaw devices remove <deviceId>

Usuń jeden wpis sparowanego urządzenia.

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

Wywołujący uwierzytelniony tokenem sparowanego urządzenia może usunąć tylko wpis własnego urządzenia. Usunięcie innego urządzenia wymaga operator.admin.

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

Przypisz etykietę operatora do sparowanego urządzenia. Etykiety są stanem po stronie właściciela: pozostają zachowane po naprawie parowania i ponownym zatwierdzeniu ról oraz nie zmieniają stabilnego deviceId.

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

• --name jest wymagane, przycinane z otaczających białych znaków, nie może być puste i może mieć najwyżej 64 znaki.
• Interfejsy wyświetlające dane (lista CLI, wykaz w interfejsie Control UI) preferują etykietę operatora zamiast nazwy wyświetlanej zgłoszonej przez klienta.
• Wywołujący korzystający ze sparowanego urządzenia bez uprawnień administratora może zmienić nazwę tylko własnego urządzenia. Zmiana nazwy innego urządzenia wymaga operator.admin.

openclaw devices clear --yes [--pending]

Zbiorczo usuń sparowane urządzenia. Wymaga --yes.

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

Opcja --pending odrzuca również wszystkie oczekujące żądania parowania.

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

Zmień token urządzenia dla roli, opcjonalnie aktualizując jego zakresy.

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

• Rola docelowa musi już istnieć w zatwierdzonym kontrakcie parowania tego urządzenia; zmiana tokenu nie może utworzyć nowej, niezatwierdzonej roli.
• Pominięcie --scope powoduje ponowne użycie zapisanych w pamięci podręcznej zatwierdzonych zakresów przechowywanego tokenu podczas kolejnych ponownych połączeń. Przekazanie jawnych wartości --scope zastępuje zapisany zestaw zakresów używany przy przyszłych ponownych połączeniach z tokenem z pamięci podręcznej.
• Wywołujący korzystający ze sparowanego urządzenia bez uprawnień administratora może zmienić tylko token własnego urządzenia, a docelowy zestaw zakresów musi mieścić się w jego własnych zakresach operatora; zmiana tokenu nie może utworzyć ani zachować tokenu o szerszych uprawnieniach niż już posiadane przez wywołującego.

Zwraca metadane zmiany tokenu w formacie JSON. Jeśli wywołujący zmienia własny token podczas uwierzytelnienia tym tokenem urządzenia, odpowiedź zawiera token zastępczy, aby klient mógł go zapisać przed ponownym połączeniem. Zmiany wykonywane współdzielonymi poświadczeniami lub przez administratora nigdy nie zwracają tokenu okaziciela.

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

Unieważnij token urządzenia dla roli.

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

Wywołujący korzystający ze sparowanego urządzenia bez uprawnień administratora może unieważnić tylko token własnego urządzenia. Unieważnienie tokenu innego urządzenia wymaga operator.admin. Docelowy zestaw zakresów musi również mieścić się w zakresach operatora wywołującego; wywołujący mający wyłącznie uprawnienia do parowania nie może unieważniać tokenów operatora z uprawnieniami administratora lub zapisu.

Uwagi

• Te polecenia wymagają zakresu operator.pairing (lub operator.admin). Role urządzeń niebędące operatorem zawsze wymagają operator.admin; zobacz Zakresy operatora.
• Zmiana i unieważnianie tokenów pozostają w zatwierdzonym zestawie ról parowania urządzenia oraz w bazowym zestawie zakresów. Przypadkowy wpis tokenu w pamięci podręcznej nie tworzy celu zarządzania tokenami.
• W sesjach tokenów sparowanych urządzeń zarządzanie innymi urządzeniami (remove, rename, rotate, revoke) jest ograniczone do własnego urządzenia, chyba że wywołujący ma operator.admin.
• Zmiana tokenu zwraca nowy token (dane wrażliwe) — traktuj go jak sekret.
• Jeśli zakres parowania jest niedostępny przez local loopback i nie przekazano jawnie --url, polecenia list/approve mogą skorzystać awaryjnie z lokalnego stanu parowania.

Lista kontrolna odzyskiwania po rozbieżności tokenów

Użyj tej procedury, gdy interfejs Control UI lub inni klienci nadal zgłaszają błędy AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH albo AUTH_SCOPE_MISMATCH.

1. Potwierdź bieżące źródło tokenu Gateway:

   openclaw config get gateway.auth.token

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

   openclaw devices list

3. Zmień token operatora dla tego urządzenia:

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

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

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

5. Ponów próbę połączenia klienta przy użyciu bieżącego współdzielonego tokenu lub hasła.

Uwagi:

• Standardowa kolejność uwierzytelniania przy ponownym połączeniu: najpierw jawny współdzielony token lub hasło, następnie jawny deviceToken, potem zapisany token urządzenia, a na końcu token inicjalizacyjny.
• Zaufany mechanizm odzyskiwania po błędzie AUTH_TOKEN_MISMATCH może tymczasowo wysłać razem współdzielony token i zapisany token urządzenia w ramach jednej ograniczonej próby ponowienia.
• AUTH_SCOPE_MISMATCH oznacza, że token urządzenia został rozpoznany, ale nie obejmuje żądanego zestawu zakresów; przed zmianą współdzielonego uwierzytelniania Gateway popraw kontrakt zatwierdzania parowania i zakresów.

Powiązane:

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

Zatwierdzanie przy pierwszym uruchomieniu Paperclip / openclaw_gateway

Agenci Paperclip łączący się przez adapter openclaw_gateway przechodzą ten sam proces zatwierdzania parowania urządzenia przy pierwszym uruchomieniu co każdy inny nowy klient. Jeśli Paperclip zgłosi openclaw_gateway_pairing_required, zatwierdź oczekujące urządzenie i ponów próbę.

openclaw devices approve --latest

Podgląd wyświetla dokładne polecenie openclaw devices approve <requestId>; zweryfikuj szczegóły, a następnie uruchom to polecenie ponownie z identyfikatorem żądania, aby je zatwierdzić. W przypadku zdalnego Gateway lub jawnych danych uwierzytelniających 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 każdym restarcie, skonfiguruj trwałe adapterConfig.devicePrivateKeyPem w Paperclip, zamiast pozwalać mu generować nową tymczasową tożsamość urządzenia przy każdym uruchomieniu:

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

Jeśli zatwierdzanie nadal kończy się niepowodzeniem, najpierw uruchom openclaw devices list, aby potwierdzić istnienie oczekującego żądania.

Powiązane

• Dokumentacja CLI
• Węzły