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) ให้เรียกใช้อีกครั้งด้วย ID คำขอที่ตรงกันทุกประการเพื่ออนุมัติ

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 ไปยังโฮสต์ของโหนด ดังนั้นคำขออาจเปลี่ยนเป็นอนุมัติแล้วไม่นานหลังจากปรากฏขึ้น ตั้งค่า sshVerify: false เพื่อปิดการตรวจสอบผ่าน SSH การตั้งค่านี้แยกจาก 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 และรายการอุปกรณ์ใน 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 หากผู้เรียกหมุนเวียนโทเค็นของตนเองขณะที่ยืนยันตัวตนด้วยโทเค็นของอุปกรณ์นั้น การตอบกลับจะรวมโทเค็นทดแทนเพื่อให้ไคลเอนต์จัดเก็บไว้ก่อนเชื่อมต่อใหม่ การหมุนเวียนแบบใช้ร่วมกัน/โดยผู้ดูแลระบบจะไม่ส่งโทเค็นผู้ถือกลับมา

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
• การหมุนเวียนโทเค็นจะส่งคืนโทเค็นใหม่ (ข้อมูลละเอียดอ่อน) — ให้จัดการเสมือนเป็นข้อมูลลับ
• หากไม่สามารถใช้ขอบเขตการจับคู่บน local loopback และไม่ได้ระบุ --url อย่างชัดเจน list/approve สามารถย้อนกลับไปใช้สถานะการจับคู่ภายในเครื่องได้

รายการตรวจสอบการกู้คืนเมื่อโทเค็นคลาดเคลื่อน

ใช้ขั้นตอนนี้เมื่อ UI ควบคุมหรือไคลเอนต์อื่นยังคงล้มเหลวด้วย AUTH_TOKEN_MISMATCH, AUTH_DEVICE_TOKEN_MISMATCH หรือ AUTH_SCOPE_MISMATCH

1. ยืนยันแหล่งที่มาของโทเค็น Gateway ปัจจุบัน:

   openclaw config get gateway.auth.token

2. แสดงรายการอุปกรณ์ที่จับคู่แล้วและระบุ ID ของอุปกรณ์ที่ได้รับผลกระทบ:

   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> ที่ตรงกันทุกประการ ตรวจสอบรายละเอียด แล้วเรียกใช้คำสั่งนั้นอีกครั้งพร้อม ID คำขอเพื่ออนุมัติ สำหรับ Gateway ระยะไกลหรือข้อมูลประจำตัวที่ระบุไว้อย่างชัดเจน ให้ระบุตัวเลือกเดิมทั้งตอนแสดงตัวอย่างและตอนอนุมัติ:

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

เพื่อหลีกเลี่ยงการอนุมัติซ้ำหลังการเริ่มระบบใหม่ทุกครั้ง ให้กำหนดค่า adapterConfig.devicePrivateKeyPem แบบถาวรใน Paperclip แทนการปล่อยให้สร้างข้อมูลประจำตัวอุปกรณ์ชั่วคราวใหม่ในการเรียกใช้แต่ละครั้ง:

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

หากการอนุมัติยังคงล้มเหลว ให้เรียกใช้ openclaw devices list ก่อนเพื่อยืนยันว่ามีคำขอที่รอดำเนินการอยู่

เนื้อหาที่เกี่ยวข้อง

• เอกสารอ้างอิง CLI
• โหนด