SmartPi 设备绑定、扫码、设备管理与 9002 故障排查。触发词:绑定 SmartPi、9002、SmartPi 连接失败、查看 SmartPi 设备、删除 SmartPi 设备。
---
name: openclaw-smartpi-setup
description: SmartPi 设备绑定、扫码、设备管理与 9002 故障排查。触发词:绑定 SmartPi、9002、SmartPi 连接失败、查看 SmartPi 设备、删除 SmartPi 设备。
---
# openclaw-smartpi-setup
## 用户意图 → Agent 动作
| 用户说 | Agent 立即执行 |
|--------|----------------|
| 绑定/添加 SmartPi 设备 | 执行 bind → 生成二维码 → 等待 WebSocket connected |
| 查看/列出 SmartPi 设备 | `exec: openclaw smartpi accounts list` |
| 删除 SmartPi 设备 | `exec: openclaw smartpi accounts remove <deviceKey>` |
---
## 绑定流程
1. `exec: openclaw smartpi accounts bind`
2. 从输出提取 `绑定ID:` 后的 bindingId
3. 生成 QR PNG(脚本见下)
4. 发送图片给用户,提示「用微信扫一扫,绑定成功我会告诉你」
5. 等待 30-120 秒,查日志 `WebSocket connected: <deviceKey>`
6. 确认连接后告知用户「设备已连接,可以对着 SmartPi 说话了」
**生成 QR 脚本(选一种):**
Python:
```python
import qrcode
qrcode.make("bindingId").save("smartpi_qr.png")
```
Node.js:
```bash
node -e "require('qrcode').toFile('smartpi_qr.png','bindingId',{type:'png'},e=>e&&console.error(e))"
```
---
## 首次安装(插件未装时)
```bash
openclaw plugins install openclaw-smartpi
openclaw gateway restart
```
然后配置(**两个关键坑**,见下方「关键坑点」),再重启 Gateway。
---
## 9002 排查
9002 = AI 未在限定时间内回复。按顺序排查:
1. `exec: openclaw plugins list` → 确认 `openclaw-smartpi: enabled`
2. `exec: openclaw smartpi accounts list` → 确认有设备
3. 查日志 `WebSocket connected` → 确认 WS 已连接
4. **向 OpenClaw 发一条文本** → 确认 AI 响应速度正常(最常见原因:本地模型慢 / MCP 阻塞 / Tools 卡住)
5. 查日志 `cannot resolve agentId` → 确认 channels 配置存在
---
## 关键坑点(必须保留)
**坑 1:`plugins.allow` 是整体替换**
`config.patch` 对数组是整体替换,不是追加。必须先 `gateway action=config.get` 读取当前配置,构造完整数组再 patch。
**坑 2:`channels` 也是整体替换**
`config.patch` 传 `channels.openclaw-smartpi` 会覆盖掉其他已有 channel(discord、telegram 等)。必须保留所有已有 channels,再追加 `openclaw-smartpi`。
**正确配置示例:**
```json
"channels": {
"openclaw-smartpi": {
"enabled": true,
"defaultAgentId": "main"
}
}
```
**坑 3:channel.id 必须匹配**
插件内部 `channel.id = "openclaw-smartpi"`,配置中必须是 `channels.openclaw-smartpi`,一字不差,否则消息无法路由,报 `cannot resolve agentId`。
---
## 常用命令
| 命令 | 用途 |
|------|------|
| `openclaw smartpi accounts list` | 查看已绑定设备 |
| `openclaw smartpi accounts bind` | 扫码绑定新设备 |
| `openclaw smartpi accounts remove <deviceKey>` | 删除设备(同时解绑云端) |
| `openclaw plugins list` | 确认插件状态 |
| `openclaw gateway restart` | 插件变更后重启 |
---
## 日志关键字
| 关键字 | 含义 |
|--------|------|
| `WebSocket connected` | 设备已上线 ✅ |
| `WebSocket disconnected` | 设备断开 |
| `cannot resolve agentId` | 缺少 `channels.openclaw-smartpi` 配置 |
| `AI response timeout` | AI 响应超时 → 导致 9002 |don't have the plugin yet? install it then click "run inline in claude" again.
this skill handles the full lifecycle of smartpi device management in openclaw: binding new devices via qr code, listing connected devices, removing devices, and troubleshooting the most common error (9002 timeout). use this when a user wants to pair a smartpi device, check device status, remove a device, or debug why the ai isn't responding to smartpi input. the skill assumes openclaw gateway is running locally with the openclaw-smartpi plugin installed.
external connections:
OPENCLAW_GATEWAY_URL, defaults to http://localhost:8080)openclaw plugins install openclaw-smartpi)required context:
openclaw commands in shelloptional:
qrcode python package: pip install qrcode pillowqrcode npm package: npm install qrcode (for node.js approach)install plugin (first time only)
openclaw plugins install openclaw-smartpiopenclaw gateway restartopenclaw plugins list includes openclaw-smartpi: enabledvalidate gateway config before binding
openclaw gateway action=config.getplugins.allow array and channels objectpatch config to enable smartpi plugin (if not already enabled)
openclaw-smartpi in plugins.allow array? if yes, skip to step 4. if no, continue.plugins.allow array that includes all existing plugins plus openclaw-smartpiopenclaw gateway action=config.patch plugins.allow=[...full array...]patch config to add smartpi channel (if not already present)
channels.openclaw-smartpi already exist? if yes, skip to step 5. if no, continue.channels object that preserves all existing channels (discord, telegram, etc.) and adds channels.openclaw-smartpi with enabled: true and defaultAgentId: mainopenclaw gateway action=config.patch channels={...full channels object...}restart gateway after config changes
openclaw gateway restartinitiate device binding
openclaw smartpi accounts bindbindingId value (appears after "绑定ID:" or similar label)generate qr code png
python3 -c "import qrcode; qrcode.make('BINDING_ID_HERE').save('smartpi_qr.png')"node -e "const qr=require('qrcode'); qr.toFile('smartpi_qr.png','BINDING_ID_HERE',(e)=>e&&console.error(e))"send qr to user and wait for device connection
WebSocket connected: followed by a deviceKeyconfirm device is online to user
openclaw smartpi accounts list to show user their new device in the listif user wants to list existing devices (instead of bind new one):
openclaw smartpi accounts listif user wants to delete a device:
openclaw smartpi accounts remove <deviceKey>if device did not connect within 120 seconds (timeout during step 8):
if gateway startup fails during step 5:
openclaw plugins list, is openclaw-smartpi listed?openclaw plugins uninstall openclaw-smartpi, then step 1)if user reports error 9002 (ai response timeout when talking to smartpi):
openclaw plugins list → confirm openclaw-smartpi: enabledopenclaw smartpi accounts list → confirm device existsWebSocket connected: <deviceKey> line is recent (within last 60s)cannot resolve agentId → if found, re-run step 4 (channels config missing or misconfigured)AI response timeout or gateway timeout messages → if found, increase timeout setting in config (beyond scope of this skill, escalate)if config.patch operation fails with "array is immutable" or similar:
if qr code generation command fails (python/node not installed):
success state:
openclaw smartpi accounts list output with status "online"WebSocket connected: <deviceKey>cannot resolve agentId errors in gateway logsfile locations:
logs/gateway.log (location varies by os/install)openclaw gateway action=config.getdata format:
binding successful:
WebSocket connected: <deviceKey>list operation successful:
delete operation successful:
list output