Hướng Dẫn Xác Thực Và Quản Lý Thiết Bị (Device Pairing) Trên OpenClaw

OpenClaw dùng cơ chế pairing (ghép cặp có phê duyệt) để đảm bảo chỉ người và thiết bị được cấp quyền mới truy cập được hệ thống.
Nói ngắn gọn: không có approve thì không được vào.

1) Pairing trong OpenClaw là gì?

Trong OpenClaw, “pairing” xuất hiện ở 2 lớp khác nhau:

1. DM Pairing: kiểm soát ai được nhắn bot (Telegram/WhatsApp/Signal/Discord…)
2. Device Pairing (Node Pairing): kiểm soát thiết bị nào được kết nối vào Gateway với vai trò node

Điểm quan trọng: cả hai đều yêu cầu owner approve.

2) DM Pairing (xác thực người nhắn bot)

Khi channel bật policy pairing, người lạ nhắn bot sẽ nhận mã pairing và tin nhắn của họ chưa được xử lý cho tới khi bạn duyệt.

Đặc điểm mã pairing

• 8 ký tự in hoa
• Hết hạn sau ~1 giờ
• Có giới hạn số request pending theo channel

Lệnh thường dùng

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Có thể dùng thêm:

• --channel <channel>
• --account <accountId> (multi-account)
• --notify (gửi thông báo sau khi approve)

Ví dụ:

openclaw pairing list --channel telegram --account work
openclaw pairing approve --channel telegram --account work <CODE> --notify

openclaw pairing list --channel telegram --account work
openclaw pairing approve --channel telegram --account work <CODE> --notify

3) Device Pairing (ghép cặp thiết bị/node)

Đây là phần bạn quan tâm nhất khi thêm iOS/Android/macOS node vào OpenClaw.

Luồng chuẩn (khuyến nghị qua Telegram + plugin device-pair)

1. Trên Telegram nhắn bot: /pair
2. Bot trả về hướng dẫn + setup code
3. Trên app OpenClaw (điện thoại): vào Settings → Gateway
4. Dán setup code và connect
5. Quay lại Telegram: /pair approve

Setup code chứa URL + token tạm thời, xem như mật khẩu ngắn hạn.

Duyệt thiết bị bằng CLI

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

4) Quản lý trạng thái thiết bị đã pair

OpenClaw lưu trạng thái device ở:

• ~/.openclaw/devices/pending.json → yêu cầu chờ duyệt
• ~/.openclaw/devices/paired.json → thiết bị đã duyệt + token

Bạn nên:

• bảo vệ thư mục này như dữ liệu nhạy cảm
• chỉ approve request bạn nhận diện được
• reject request lạ ngay

5) Phân biệt nhanh: devices vs nodes

Nhiều người hay nhầm:

• openclaw devices ... → luồng ghép cặp thiết bị WS node hiện tại (quan trọng)
• openclaw nodes pending/approve ... → luồng node.pair.* riêng (gateway-owned pairing store), không phải cổng chính WS handshake

Nếu mục tiêu là thêm điện thoại/node thực tế vào hệ thống hiện tại: ưu tiên devices.

6) Best Practices bảo mật khi pairing

• Chỉ approve khi biết rõ người/thiết bị
• Không chia sẻ setup code/token qua kênh công khai
• Dọn request pending cũ định kỳ
• Nếu nghi ngờ lộ token: reject/rotate bằng cách re-pair thiết bị
• Kiểm tra định kỳ:

openclaw devices list
openclaw pairing list telegram

openclaw devices list
openclaw pairing list telegram