openclaw-smartpi-setup

概述

openclaw-smartpi 插件允许用户通过 SmartPi 语音设备与 OpenClaw 交互。用户说话后音频通过 WebSocket 传到 OpenClaw，AI 回复后通过同一连接返回，SmartPi 设备播报语音回复。

安装流程

第一步：安装插件并重启

openclaw plugins install openclaw-smartpi
openclaw gateway restart

重启后插件加载，可通过 openclaw plugins list 确认 openclaw-smartpi 状态为 enabled。

第二步：扫码绑定设备

openclaw smartpi accounts bind

执行后：

1. 调用云端接口生成 bindingId（有效期 30 分钟）
2. 终端打印 QR 码（ASCII 格式，不可直接扫描）
3. 从输出中提取 绑定ID: 后面的 bindingId，生成 QR 图片（见下方）
4. 将 QR 图片发送给用户，用微信扫描
5. 扫码后终端显示 绑定成功，自动建立 WebSocket 长连接

设备信息保存在：

~/.xxclaw/openclaw-smartpi/accounts/\x3CdeviceKey>.json

生成可扫描的 QR 图片

终端打印的 QR 码为 ASCII 格式，无法直接扫描。需从命令输出中提取 绑定ID: 后面的 bindingId，生成 PNG 图片供微信扫码。

方法（Python qrcode 库）：

import qrcode
binding_id = "6b20121312b600a96a75e636d5222079"  # 替换为实际 bindingId
img = qrcode.make(binding_id)
img.save("C:/Users/15352/.qclaw/workspace/smartpi_qr.png")
print("Done")

方法（Node.js qrcode 包）：

npm install -g qrcode
node -e "const QR = require('qrcode'); QR.toFile('C:/Users/15352/.qclaw/workspace/smartpi_qr.png', '绑定ID', {type: 'png'}, (err) => { if(err) console.error(err); else console.log('Done'); });"

生成后，将 smartpi_qr.png 发送给用户扫描。

第三步：验证设备状态

openclaw smartpi accounts list

正常输出：

SmartPi 设备列表:
- JL_17T_xxxx

同时检查 Gateway 日志中是否有 WebSocket connected: \x3CdeviceKey>。

第四步：开始使用

确保 Gateway 正在运行：

openclaw gateway status

对着 SmartPi 设备说话，QClaw 会处理输入并以语音回复。

故障排查

错误码 9002：该功能暂不可用

可能原因：

1. OpenClaw Gateway 未正常处理消息 — AI 模型未配置或响应失败，导致 SmartPi 服务端收不到有效回复
2. WebSocket 连接已断开 — 设备连接已断开，SmartPi 服务端转发请求时失败
3. 插件未正确加载 — openclaw-smartpi 插件安装后未重启 Gateway，或插件加载失败
4. 设备绑定凭证异常 — bindId 或 token 未正确保存，导致后续消息验证失败

排查步骤：

# 1. 确认插件已加载
openclaw plugins list
# 确认 openclaw-smartpi 状态为 enabled

# 2. 确认设备已绑定且连接正常
openclaw smartpi accounts list
# 检查网关日志：openclaw gateway status
# 日志中应有：[gateway] WebSocket connected: \x3CdeviceKey>

# 3. 确认 AI 模型已配置（能正常回复消息）
test: 直接向 OpenClaw 发一条消息，确认 AI 能正常回复

# 4. 重启 Gateway 重刷连接
openclaw gateway restart
# 重启后再次检查设备连接状态

若以上都正常，查看 OpenClaw 日志中是否有错误信息：~/.openclaw/logs/openclaw-YYYY-MM-DD.log

设备无法连接

1. 重新绑定：openclaw smartpi accounts bind
2. 查看设备列表：openclaw smartpi accounts list
3. 查看日志中的连接错误信息

连接频繁断开

插件内置指数退避重连（1s → 2s → 4s... 最大 60s），一般会自动恢复。若频繁断开：

1. 检查网络稳定性
2. 查看日志中的重连记录

设备管理命令

查看已绑定设备：

openclaw smartpi accounts list

删除设备：

openclaw smartpi accounts remove \x3CdeviceKey>

卸载流程

卸载插件前，请先移除已绑定的设备账户（否则残留账户文件可能导致重新安装后行为异常）。

# 1. 查看当前绑定的设备
openclaw smartpi accounts list

# 2. 逐一删除所有设备账户
openclaw smartpi accounts remove \x3CdeviceKey>
# （如有多个设备，重复此命令逐一删除）

# 3. 确认账户目录已清空
openclaw smartpi accounts list
# 应输出空列表

# 4. 卸载插件
openclaw plugins uninstall openclaw-smartpi

# 5. 重启 Gateway
openclaw gateway restart

如需彻底清理，可手动删除残留文件：

Remove-Item -Recurse -Force "$env:USERPROFILE\.xxclaw\openclaw-smartpi"

配置文件位置

注意事项

• sendText 未实现：SmartPi 是被动接收模式（设备说话 → OpenClaw 回复），不支持主动发送文本
• 心跳间隔：30 秒（ping/pong）
• 绑定 ID 有效期：30 分钟