配对
设备配对（Device Pairing）是一种安全的设备认证流程，允许新设备在无需预先知道 Token 的情况下安全接入 Gateway。
配对流程概览
text
┌──────────────┐ ┌──────────────┐
│ 新设备 │ │ 已授权设备 │
│ (手机) │ │ (电脑) │
└──────┬───────┘ └──────┬───────┘
│ │
│ 1. 发起配对请求 │
│ ──────────▶ Gateway │
│ │
│ 2. 生成配对码 │
│ 3. 通知已授权设备 ──────▶│
│ │
│ │ 4. 用户查看配对码
│ │ 确认或拒绝
│ │
│ 5. 审批结果 │
│ ◀────────── Gateway ◀─────────────│
│ │
│ 6. 收到设备 Token │
│ │发起配对
在新设备上
bash
# 发起配对请求
openclaw pair输出：
text
🔗 Pairing Request Sent
Gateway: My Gateway (192.168.1.10:18789)
Device: iPhone-15
Pair Code: 847 291
Waiting for approval from an authorized device...
Please approve on your existing device.
[Press Ctrl+C to cancel]配对码
6 位数配对码（Pair Code）用于防止中间人攻击。请确认两端显示的配对码一致。
指定 Gateway
bash
# 自动发现局域网 Gateway
openclaw pair
# 手动指定 Gateway
openclaw pair --host 192.168.1.10 --port 18789
# 使用 Gateway URL
openclaw pair --url ws://192.168.1.10:18789审批配对
在已授权设备上
当有新设备请求配对时，已授权设备会收到通知：
text
📱 New Pairing Request
Device: iPhone-15
IP: 192.168.1.20
Pair Code: 847 291
Time: 2025-01-15 10:30:00
Approve this device? [y/N]:CLI 审批命令
bash
# 查看待审批的配对请求
openclaw pair list
# 审批指定请求
openclaw pair approve <request-id>
# 拒绝指定请求
openclaw pair reject <request-id>
# 使用配对码审批
openclaw pair approve --code 847291批量管理
bash
# 查看所有待审批请求
openclaw pair list --pending输出：
text
Pending Pairing Requests:
ID Device IP Code Time
pr_001 iPhone-15 192.168.1.20 847 291 2 min ago
pr_002 Linux-Server 10.0.0.5 392 158 5 min ago配对协议
请求消息
json
{
"type": "pair-request",
"deviceName": "iPhone-15",
"deviceType": "mobile",
"clientVersion": "1.2.0"
}Gateway 生成配对码
json
{
"type": "pair-challenge",
"requestId": "pr_001",
"pairCode": "847291",
"expiresIn": 300
}审批消息
json
{
"type": "pair-approve",
"requestId": "pr_001",
"pairCode": "847291",
"approvedBy": "dev_macbook"
}配对成功
json
{
"type": "pair-ok",
"deviceId": "dev_iphone15",
"token": "device-specific-token-xxx",
"expiresAt": null
}配对拒绝
json
{
"type": "pair-rejected",
"requestId": "pr_001",
"reason": "User rejected the pairing request"
}配对配置
json5
{
"gateway": {
"pairing": {
"enabled": true,
"codeLength": 6, // 配对码长度
"codeExpiry": 300, // 配对码有效期（秒）
"maxPendingRequests": 5, // 最大待审批请求数
"requireCode": true, // 是否要求验证配对码
"autoApprove": false // 自动审批（⚠️ 不推荐）
}
}
}不要自动审批
autoApprove: true 会自动批准所有配对请求，任何发现 Gateway 的设备都会获得访问权限。仅在受信任的封闭网络中使用。
撤销配对
撤销特定设备
bash
# 列出已配对设备
openclaw devices list
# 撤销指定设备
openclaw devices revoke dev_iphone15text
Revoke device "iPhone-15" (dev_iphone15)?
This will immediately disconnect the device and invalidate its token.
[y/N]: y
Device revoked successfully.撤销所有设备
bash
# 撤销除当前设备外的所有设备
openclaw devices revoke-all即时生效
撤销操作立即断开目标设备的所有连接，并使其 Token 失效。该设备需要重新配对才能接入。
安全考虑
- 配对码验证 — 始终确认两端显示的配对码一致
- 配对超时 — 配对码在 5 分钟后过期
- 物理确认 — 配对需要在已授权设备上手动确认
- 独立 Token — 每个设备获得唯一 Token，可独立撤销
- 审计 — 所有配对和撤销操作都记录在日志中