SmartPi 语音控制插件

通过 SmartPi 语音设备与 OpenClaw 进行交互的插件。支持语音命令和语音询问，让用户可以通过语音与 AI 助手对话。

功能特性（最新）

• 语音交互：通过 SmartPi 设备进行语音输入，AI 回复以语音播报
• 扫码绑定：通过微信小程序扫码绑定设备，自动获取凭证
• 多设备管理：支持绑定、删除、查看多个 SmartPi 设备（CLI）
• WebSocket 连接：自动维护与设备的长连接，内置心跳检测
• 重连策略：指数退避并带抖动；连续失败后进入慢重连模式
• 绑定状态自检：启动/轮询时自检服务端绑定状态，自动清理已解绑设备
• 热插拔支持：本地凭证变化自动同步，无需重启即可自动连/断（每 5s 轮询）
• 流式回复：Agent 回复以增量流式下发，完成/错误事件按协议发送

安装

方式：通过 OpenClaw 安装（推荐）

openclaw plugins install openclaw-smartpi

安装完成后请重启 OpenClaw 以加载插件。

环境要求：

• Node.js >= 18

设备管理（CLI 命令）

设备管理通过 OpenClaw CLI 命令执行，在控制台运行：

扫码绑定设备

openclaw smartpi accounts bind

执行后会生成二维码，使用微信小程序扫描完成绑定。绑定成功后自动保存凭证并建立连接。

绑定流程：

1. 执行 bind 命令，生成绑定二维码
2. 使用微信小程序扫描二维码
3. 等待绑定成功，自动保存 deviceKey 和 token
4. 自动建立 WebSocket 连接

查看设备列表

openclaw smartpi accounts list

输出示例：

SmartPi 设备列表:
- JX_A7T_7C3E821DBA9F
- JX_B8U_8D4F932ECB0A

删除设备

openclaw smartpi accounts remove <deviceKey>

查看连接状态

openclaw smartpi status <deviceKey>

输出示例：

JX_A7T_7C3E821DBA9F connected=true updatedAt=2025-01-01T12:00:00.000Z

清理本地状态

openclaw smartpi purge

说明：删除本地账号索引与凭证文件。用于排障或完全重置绑定。

使用方式

1. 启动 OpenClaw

openclaw

2. 设备连接

插件启动后会自动连接已配置的 SmartPi 设备。连接成功后，日志会显示：

[gateway] 设备 <deviceKey> 连接成功

3. 语音交互

通过 SmartPi 设备进行语音输入，AI 会自动处理并回复。回复内容将以语音形式播报。

配置文件位置

• 账号数据：~/.openclaw/openclaw-smartpi/accounts/<deviceKey>.json
• 账号索引：~/.openclaw/openclaw-smartpi/accounts.json（保存 deviceKey 列表）
• 连接状态：~/.openclaw/openclaw-smartpi/status/<deviceKey>.json
• 日志文件：/tmp/openclaw/openclaw-YYYY-MM-DD.log

可通过环境变量覆盖根目录：

• OPENCLAW_STATE_DIR=/path/to/dir

日志级别

通过环境变量设置日志级别：

export OPENCLAW_LOG_LEVEL=DEBUG  # 可选: TRACE, DEBUG, INFO, WARN, ERROR, FATAL

故障排查

设备无法连接

1. 重新扫码绑定：openclaw smartpi accounts bind
2. 确认设备已配置：openclaw smartpi accounts list
3. 查看日志中的错误信息
4. 使用 openclaw smartpi status <deviceKey> 检查本地连接状态

连接频繁断开

1. 检查网络连接稳定性
2. 查看日志中的重连记录（包含指数退避与慢重连提示）

语音消息无响应

1. 确认 OpenClaw 已正确配置 AI 模型
2. 检查日志中是否有消息处理错误
3. 确认设备连接状态正常
4. 若设备已在服务端解绑，插件将自动清理本地凭证；请重新绑定

开发

构建

npm run build

类型检查

npm run typecheck

许可证

ISC