openclaw devices

Verwalten Sie Geräte-Kopplungsanfragen und gerätebezogene Token.

Allgemeine Optionen

• --url <url>: Gateway-WebSocket-URL (standardmäßig gateway.remote.url, sofern konfiguriert)
• --token <token>: Gateway-Token (falls erforderlich)
• --password <password>: Gateway-Passwort (Passwortauthentifizierung)
• --timeout <ms>: RPC-Zeitüberschreitung
• --json: JSON-Ausgabe (für Skripte empfohlen)

Befehle

openclaw devices list

Listet ausstehende Kopplungsanfragen und gekoppelte Geräte auf.

openclaw devices listopenclaw devices list --json

Bei einer ausstehenden Anfrage für ein bereits gekoppeltes Gerät zeigt die Ausgabe den angeforderten Zugriff neben dem derzeit genehmigten Zugriff des Geräts an. Dadurch sind Erweiterungen von Berechtigungsumfang oder Rolle erkennbar, statt wie eine verloren gegangene Kopplung zu wirken.

Anzeigenamen gekoppelter Geräte verwenden diese Prioritätsreihenfolge: Betreiberbezeichnung (operatorLabel aus devices rename), dann displayName des Clients, dann clientId, dann deviceId.

openclaw devices approve [requestId] [--latest]

Genehmigt eine ausstehende Kopplungsanfrage anhand der exakten requestId. Wenn Sie requestId weglassen oder --latest übergeben, wird nur eine Vorschau der neuesten ausstehenden Anfrage angezeigt und der Befehl beendet sich (Code 1). Führen Sie ihn zur Genehmigung erneut mit der exakten Anfrage-ID aus.

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

Genehmigungsverhalten:

• Wenn das Gerät bereits gekoppelt ist und weiter gefasste Berechtigungsumfänge oder eine andere Rolle anfordert, behält OpenClaw die bestehende Genehmigung bei und erstellt eine neue ausstehende Erweiterungsanfrage. Vergleichen Sie vor der Genehmigung in openclaw devices list Requested mit Approved oder zeigen Sie mit --latest eine Vorschau an.
• Die Genehmigung einer node-Rolle oder einer anderen Nicht-Betreiberrolle erfordert operator.admin. operator.pairing genügt für Genehmigungen von Betreibergeräten, jedoch nur, wenn die angeforderten Betreiber-Berechtigungsumfänge innerhalb der eigenen Berechtigungsumfänge des Aufrufers bleiben. Siehe Betreiber-Berechtigungsumfänge.
• Wenn gateway.nodes.pairing.autoApproveCidrs konfiguriert ist, können erstmalige Anfragen mit role: node von übereinstimmenden Client-IP-Adressen automatisch genehmigt werden, bevor sie in dieser Liste erscheinen. Standardmäßig deaktiviert; gilt niemals für Betreiber-/Browser-Clients oder Erweiterungsanfragen.
• gateway.nodes.pairing.sshVerify (standardmäßig aktiviert) genehmigt erstmalige Anfragen mit role: node automatisch, wenn das Gateway den Geräteschlüssel per SSH gegenüber dem Node-Host verifiziert. Anfragen können daher kurz nach ihrem Erscheinen bereits als genehmigt aufgelöst werden. Legen Sie sshVerify: false fest, um die SSH-Verifizierung zu deaktivieren. Dies ist unabhängig von autoApproveCidrs; deaktivieren Sie daher auch diese Option, wenn ausschließlich manuelle Kopplung gewünscht ist.

openclaw devices reject <requestId>

Lehnt eine ausstehende Geräte-Kopplungsanfrage ab.

openclaw devices reject <requestId>

openclaw devices remove <deviceId>

Entfernt einen Eintrag eines gekoppelten Geräts.

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

Ein Aufrufer, der mit dem Token eines gekoppelten Geräts authentifiziert ist, kann nur den Eintrag seines eigenen Geräts entfernen. Das Entfernen eines anderen Geräts erfordert operator.admin.

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

Weist einem gekoppelten Gerät eine Betreiberbezeichnung zu. Bezeichnungen sind betreiberseitiger Zustand: Sie bleiben nach Reparaturen der Kopplung und erneuten Rollengenehmigungen erhalten und ändern die stabile deviceId nicht.

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

• --name ist erforderlich, wird von umgebenden Leerzeichen bereinigt, darf nicht leer sein und ist auf 64 Zeichen begrenzt.
• Anzeigeoberflächen (CLI-Liste, Inventar der Control UI) bevorzugen die Betreiberbezeichnung gegenüber dem vom Client gemeldeten Anzeigenamen.
• Ein Aufrufer eines gekoppelten Geräts ohne Administratorrechte kann nur sein eigenes Gerät umbenennen. Das Umbenennen eines anderen Geräts erfordert operator.admin.

openclaw devices clear --yes [--pending]

Löscht gekoppelte Geräte gesammelt. Erfordert --yes.

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

--pending lehnt außerdem alle ausstehenden Kopplungsanfragen ab.

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

Erneuert ein Geräte-Token für eine Rolle und aktualisiert optional dessen Berechtigungsumfänge.

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

• Die Zielrolle muss bereits im genehmigten Kopplungsvertrag dieses Geräts vorhanden sein; durch die Erneuerung kann keine neue, nicht genehmigte Rolle erzeugt werden.
• Wenn Sie --scope weglassen, werden bei späteren Neuverbindungen die zwischengespeicherten genehmigten Berechtigungsumfänge des gespeicherten Tokens wiederverwendet. Durch die Übergabe ausdrücklicher --scope-Werte wird die gespeicherte Menge der Berechtigungsumfänge für künftige Neuverbindungen mit zwischengespeicherten Token ersetzt.
• Ein Aufrufer eines gekoppelten Geräts ohne Administratorrechte kann nur das Token seines eigenen Geräts erneuern, und die Zielmenge der Berechtigungsumfänge muss innerhalb der eigenen Betreiber-Berechtigungsumfänge des Aufrufers bleiben. Durch die Erneuerung kann kein weiter gefasstes Token erzeugt oder beibehalten werden, als der Aufrufer bereits besitzt.

Gibt Metadaten zur Erneuerung als JSON zurück. Wenn der Aufrufer sein eigenes Token erneuert, während er mit diesem Geräte-Token authentifiziert ist, enthält die Antwort das Ersatz-Token, damit der Client es vor der Neuverbindung dauerhaft speichern kann. Gemeinsam verwendete Erneuerungen oder Erneuerungen durch Administratoren geben das Bearer-Token niemals zurück.

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

Widerruft ein Geräte-Token für eine Rolle.

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

Ein Aufrufer eines gekoppelten Geräts ohne Administratorrechte kann nur das Token seines eigenen Geräts widerrufen. Das Widerrufen des Tokens eines anderen Geräts erfordert operator.admin. Die Zielmenge der Berechtigungsumfänge muss außerdem innerhalb der eigenen Betreiber-Berechtigungsumfänge des Aufrufers liegen; Aufrufer mit ausschließlicher Kopplungsberechtigung können keine Administrator-/Schreib-Token von Betreibern widerrufen.

Hinweise

• Diese Befehle erfordern den Berechtigungsumfang operator.pairing (oder operator.admin). Geräte mit Nicht-Betreiberrollen erfordern immer operator.admin; siehe Betreiber-Berechtigungsumfänge.
• Token-Erneuerung und -Widerruf bleiben innerhalb der genehmigten Kopplungsrollen und des grundlegenden Berechtigungsumfangs des Geräts. Ein verwaister zwischengespeicherter Token-Eintrag gewährt kein Ziel für die Token-Verwaltung.
• Bei Sitzungen mit Token gekoppelter Geräte ist die geräteübergreifende Verwaltung (remove, rename, rotate, revoke) auf das eigene Gerät beschränkt, sofern der Aufrufer nicht über operator.admin verfügt.
• Die Token-Erneuerung gibt ein neues Token zurück (vertraulich) — behandeln Sie es wie ein Geheimnis.
• Wenn der Kopplungs-Berechtigungsumfang auf local loopback nicht verfügbar ist und kein ausdrückliches --url übergeben wird, können list/approve auf den lokalen Kopplungszustand zurückgreifen.

Checkliste zur Behebung abweichender Token

Verwenden Sie diese Checkliste, wenn die Control UI oder andere Clients wiederholt mit AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH oder AUTH_SCOPE_MISMATCH fehlschlagen.

1. Bestätigen Sie die aktuelle Quelle des Gateway-Tokens:

   openclaw config get gateway.auth.token

2. Listen Sie die gekoppelten Geräte auf und ermitteln Sie die ID des betroffenen Geräts:

   openclaw devices list

3. Erneuern Sie das Betreiber-Token für das betroffene Gerät:

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

4. Wenn die Erneuerung nicht ausreicht, entfernen Sie die veraltete Kopplung und genehmigen Sie sie erneut:

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

5. Versuchen Sie die Client-Verbindung erneut mit dem aktuellen gemeinsam verwendeten Token/Passwort.

Hinweise:

• Normale Authentifizierungspriorität bei Neuverbindungen: zuerst ausdrücklich angegebenes gemeinsam verwendetes Token/Passwort, dann ausdrücklich angegebenes deviceToken, dann gespeichertes Geräte-Token, dann Bootstrap-Token.
• Bei vertrauenswürdiger Wiederherstellung nach AUTH_TOKEN_MISMATCH können vorübergehend sowohl das gemeinsam verwendete Token als auch das gespeicherte Geräte-Token zusammen für einen begrenzten Wiederholungsversuch gesendet werden.
• AUTH_SCOPE_MISMATCH bedeutet, dass das Geräte-Token erkannt wurde, aber nicht die angeforderte Menge an Berechtigungsumfängen enthält. Korrigieren Sie den Genehmigungsvertrag für Kopplung und Berechtigungsumfänge, bevor Sie die gemeinsam verwendete Gateway-Authentifizierung ändern.

Verwandte Themen:

• Fehlerbehebung bei der Dashboard-Authentifizierung
• Gateway-Fehlerbehebung

Erstmalige Genehmigung für Paperclip / openclaw_gateway

Paperclip-Agenten, die über den Adapter openclaw_gateway eine Verbindung herstellen, durchlaufen dieselbe erstmalige Genehmigung der Gerätekopplung wie jeder andere neue Client. Wenn Paperclip openclaw_gateway_pairing_required meldet, genehmigen Sie das ausstehende Gerät und versuchen Sie es erneut.

openclaw devices approve --latest

Die Vorschau gibt den exakten Befehl openclaw devices approve <requestId> aus. Überprüfen Sie die Details und führen Sie diesen Befehl anschließend erneut mit der Anfrage-ID aus, um die Anfrage zu genehmigen. Übergeben Sie bei einem entfernten Gateway oder ausdrücklichen Anmeldedaten während der Vorschau und der Genehmigung dieselben Optionen:

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

Um eine erneute Genehmigung nach jedem Neustart zu vermeiden, konfigurieren Sie in Paperclip ein dauerhaftes adapterConfig.devicePrivateKeyPem, anstatt bei jedem Durchlauf eine neue kurzlebige Geräteidentität erzeugen zu lassen:

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

Wenn die Genehmigung weiterhin fehlschlägt, führen Sie zuerst openclaw devices list aus, um zu bestätigen, dass eine ausstehende Anfrage vorhanden ist.

Verwandte Themen

• CLI-Referenz
• Nodes