openclaw devices

Kelola permintaan pemasangan perangkat dan token yang cakupannya terbatas pada perangkat.

Opsi umum

• --url <url>: URL WebSocket Gateway (secara default menggunakan gateway.remote.url jika dikonfigurasi)
• --token <token>: Token Gateway (jika diperlukan)
• --password <password>: Kata sandi Gateway (autentikasi kata sandi)
• --timeout <ms>: Batas waktu RPC
• --json: Keluaran JSON (disarankan untuk pembuatan skrip)

Perintah

openclaw devices list

Cantumkan permintaan pemasangan yang tertunda dan perangkat yang telah dipasangkan.

openclaw devices listopenclaw devices list --json

Untuk permintaan tertunda pada perangkat yang sudah dipasangkan, keluaran menampilkan akses yang diminta di samping akses perangkat yang saat ini disetujui, sehingga peningkatan cakupan/peran terlihat dan tidak tampak seperti pemasangan yang hilang.

Nama tampilan perangkat yang dipasangkan menggunakan urutan prioritas berikut: label operator (operatorLabel dari devices rename), lalu displayName klien, lalu clientId, kemudian deviceId.

openclaw devices approve [requestId] [--latest]

Setujui permintaan pemasangan yang tertunda berdasarkan requestId yang tepat. Menghilangkan requestId, atau memberikan --latest, hanya menampilkan pratinjau permintaan tertunda terbaru lalu keluar (kode 1); jalankan kembali dengan ID permintaan yang tepat untuk menyetujuinya.

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

Perilaku persetujuan:

• Jika perangkat sudah dipasangkan dan meminta cakupan atau peran yang lebih luas, OpenClaw mempertahankan persetujuan yang ada dan membuat permintaan peningkatan baru yang tertunda. Bandingkan Requested dengan Approved di openclaw devices list, atau tampilkan pratinjau dengan --latest, sebelum menyetujui.
• Menyetujui peran node atau peran nonoperator lainnya memerlukan operator.admin. operator.pairing cukup untuk persetujuan perangkat operator, tetapi hanya jika cakupan operator yang diminta tetap berada dalam cakupan pemanggil sendiri. Lihat Cakupan operator.
• Jika gateway.nodes.pairing.autoApproveCidrs dikonfigurasi, permintaan pertama kali dengan role: node dari IP klien yang cocok dapat disetujui secara otomatis sebelum muncul dalam daftar ini. Dinonaktifkan secara default; tidak pernah berlaku untuk klien operator/peramban atau permintaan peningkatan.
• gateway.nodes.pairing.sshVerify (aktif secara default) secara otomatis menyetujui permintaan pertama kali dengan role: node ketika Gateway memverifikasi kunci perangkat melalui SSH ke hos Node. Karena itu, permintaan dapat berubah menjadi disetujui tidak lama setelah muncul. Tetapkan sshVerify: false untuk menonaktifkan verifikasi SSH; pengaturan ini terpisah dari autoApproveCidrs, jadi hapus pengaturan tersebut juga agar pemasangan hanya dilakukan secara manual.

openclaw devices reject <requestId>

Tolak permintaan pemasangan perangkat yang tertunda.

openclaw devices reject <requestId>

openclaw devices remove <deviceId>

Hapus satu entri perangkat yang dipasangkan.

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

Pemanggil yang diautentikasi dengan token perangkat yang dipasangkan hanya dapat menghapus entri perangkatnya sendiri. Menghapus perangkat lain memerlukan operator.admin.

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

Tetapkan label operator ke perangkat yang dipasangkan. Label merupakan status di sisi pemilik: label tetap bertahan setelah perbaikan pemasangan dan persetujuan ulang peran, serta tidak mengubah deviceId yang stabil.

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

• --name wajib diberikan, dipangkas spasi di awal dan akhirnya, tidak boleh kosong, dan dibatasi hingga 64 karakter.
• Permukaan tampilan (daftar CLI, inventaris UI Kontrol) mengutamakan label operator daripada nama tampilan yang dilaporkan klien.
• Pemanggil perangkat terpasang yang bukan admin hanya dapat mengganti nama perangkatnya sendiri. Mengganti nama perangkat lain memerlukan operator.admin.

openclaw devices clear --yes [--pending]

Hapus perangkat yang dipasangkan secara massal. Memerlukan --yes.

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

--pending juga menolak semua permintaan pemasangan yang tertunda.

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

Rotasi token perangkat untuk suatu peran, dengan opsi memperbarui cakupannya.

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

• Peran target harus sudah ada dalam kontrak pemasangan perangkat yang disetujui; rotasi tidak dapat menerbitkan peran baru yang belum disetujui.
• Menghilangkan --scope akan menggunakan kembali cakupan yang disetujui dan tersimpan dalam tembolok token pada penyambungan ulang berikutnya. Memberikan nilai --scope secara eksplisit akan mengganti kumpulan cakupan tersimpan untuk penyambungan ulang token tembolok pada masa mendatang.
• Pemanggil perangkat terpasang yang bukan admin hanya dapat merotasi token perangkatnya sendiri, dan kumpulan cakupan target harus tetap berada dalam cakupan operator milik pemanggil sendiri; rotasi tidak dapat menerbitkan atau mempertahankan token yang cakupannya lebih luas daripada yang sudah dimiliki pemanggil.

Mengembalikan metadata rotasi sebagai JSON. Jika pemanggil merotasi tokennya sendiri saat diautentikasi dengan token perangkat tersebut, respons menyertakan token pengganti agar klien dapat menyimpannya sebelum menyambung kembali. Rotasi bersama/admin tidak pernah menampilkan kembali token pembawa.

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

Cabut token perangkat untuk suatu peran.

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

Pemanggil perangkat terpasang yang bukan admin hanya dapat mencabut token perangkatnya sendiri. Mencabut token perangkat lain memerlukan operator.admin. Kumpulan cakupan target juga harus berada dalam cakupan operator milik pemanggil sendiri; pemanggil yang hanya memiliki izin pemasangan tidak dapat mencabut token operator admin/tulis.

Catatan

• Perintah ini memerlukan cakupan operator.pairing (atau operator.admin). Peran perangkat nonoperator selalu memerlukan operator.admin; lihat Cakupan operator.
• Rotasi dan pencabutan token tetap berada dalam kumpulan peran pemasangan serta batas dasar cakupan yang disetujui untuk perangkat tersebut. Entri token tembolok yang tersesat tidak memberikan target pengelolaan token.
• Untuk sesi token perangkat terpasang, pengelolaan lintas perangkat (remove, rename, rotate, revoke) hanya dapat dilakukan terhadap perangkat sendiri kecuali pemanggil memiliki operator.admin.
• Rotasi token mengembalikan token baru (sensitif) — perlakukan sebagai rahasia.
• Jika cakupan pemasangan tidak tersedia pada local loopback dan tidak ada --url eksplisit yang diberikan, list/approve dapat beralih ke status pemasangan lokal sebagai cadangan.

Daftar periksa pemulihan penyimpangan token

Gunakan ini saat UI Kontrol atau klien lain terus gagal dengan AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH, atau AUTH_SCOPE_MISMATCH.

1. Konfirmasikan sumber token Gateway saat ini:

   openclaw config get gateway.auth.token

2. Cantumkan perangkat yang dipasangkan dan identifikasi ID perangkat yang terdampak:

   openclaw devices list

3. Rotasi token operator untuk perangkat yang terdampak:

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

4. Jika rotasi tidak cukup, hapus pemasangan yang kedaluwarsa dan setujui kembali:

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

5. Coba kembali koneksi klien dengan token/kata sandi bersama saat ini.

Catatan:

• Urutan prioritas autentikasi penyambungan ulang normal: token/kata sandi bersama yang eksplisit terlebih dahulu, lalu deviceToken eksplisit, kemudian token perangkat tersimpan, lalu token bootstrap.
• Pemulihan AUTH_TOKEN_MISMATCH tepercaya dapat mengirim token bersama dan token perangkat tersimpan secara bersamaan untuk satu percobaan ulang terbatas.
• AUTH_SCOPE_MISMATCH berarti token perangkat dikenali tetapi tidak membawa kumpulan cakupan yang diminta; perbaiki kontrak persetujuan pemasangan/cakupan sebelum mengubah autentikasi Gateway bersama.

Terkait:

• Pemecahan masalah autentikasi dasbor
• Pemecahan masalah Gateway

Persetujuan penggunaan pertama Paperclip / openclaw_gateway

Agen Paperclip yang terhubung melalui adaptor openclaw_gateway menjalani persetujuan pemasangan perangkat pada penggunaan pertama yang sama seperti klien baru lainnya. Jika Paperclip melaporkan openclaw_gateway_pairing_required, setujui perangkat yang tertunda dan coba kembali.

openclaw devices approve --latest

Pratinjau mencetak perintah openclaw devices approve <requestId> yang tepat; verifikasi detailnya, lalu jalankan kembali perintah tersebut dengan ID permintaan untuk menyetujuinya. Untuk Gateway jarak jauh atau kredensial eksplisit, berikan opsi yang sama saat menampilkan pratinjau dan menyetujui:

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

Agar tidak perlu menyetujui ulang setelah setiap mulai ulang, konfigurasikan adapterConfig.devicePrivateKeyPem persisten di Paperclip alih-alih membiarkannya menghasilkan identitas perangkat sementara baru pada setiap eksekusi:

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

Jika persetujuan terus gagal, jalankan openclaw devices list terlebih dahulu untuk memastikan adanya permintaan yang tertunda.

Terkait

• Referensi CLI
• Node