openclaw-smartpi

SmartPi 设备绑定、扫码、设备管理与连接故障排查。Use when the user mentions binding SmartPi, SmartPi QR code, 9002, SmartPi connection failure, listing SmartPi devices, or removing a SmartPi device.

SmartPi

帮助用户完成 SmartPi 插件安装检查、设备扫码绑定、设备列表查看、设备删除，以及 9002 / 连接失败等常见问题排查。

设计原则

• 元信息负责触发：description 必须直接覆盖用户常见说法，例如 SmartPi 绑定、二维码、9002、连接失败、查看设备、删除设备。
• 正文负责执行：按任务给出明确步骤、成功判定、失败分支和用户输出。
• 本地优先：优先使用本机 openclaw 命令、Gateway 配置和日志，不假设外部服务可用。
• 最小副作用：删除设备、安装插件、重启 Gateway、修改配置前必须说明影响并征得用户确认。

触发条件

当用户提出以下请求时使用本 Skill：

• 绑定设备：绑定 SmartPi、添加 SmartPi、生成 SmartPi 二维码、扫码绑定。
• 设备管理：查看 SmartPi 设备、列出已绑定设备、删除 SmartPi 设备。
• 连接故障：SmartPi 连接失败、设备不在线、WebSocket 断开。
• 9002 故障：用户看到 9002、AI response timeout、语音请求无响应或超时。
• 插件配置：安装 openclaw-smartpi、检查插件是否启用、修复 channels.openclaw-smartpi。

不适用场景

• 用户问题与 SmartPi、OpenClaw Gateway、openclaw-smartpi 插件无关。
• 用户要求开发新功能、改插件源码或调试非 SmartPi 通道时，应转入代码分析/开发类流程。
• 用户只询问泛化 IoT、语音识别或硬件设计知识时，不应直接执行 OpenClaw 命令。

快速路由

用户意图	首选流程	主要成功判定
绑定/添加 SmartPi	流程：绑定设备	日志出现 WebSocket connected: <deviceKey>
查看/列出设备	流程：查看设备	accounts list 返回设备列表
删除设备	流程：删除设备	删除命令成功且列表不再包含该设备
安装/启用插件	流程：首次安装或修复插件	plugins list 显示 openclaw-smartpi: enabled
9002/超时	流程：9002 排查	定位为连接、路由或 AI 响应链路问题

执行前检查

在执行会改变状态的动作前，先确认用户意图是否明确。

1. 检查 OpenClaw CLI 是否可用：openclaw --help
2. 检查插件状态：openclaw plugins list
3. 检查已绑定设备：openclaw smartpi accounts list
4. 若需要修改配置，先读取完整配置，再构造完整 patch。

流程：绑定设备

目标

生成 SmartPi 绑定二维码，让用户扫码绑定，并确认设备通过 WebSocket 上线。

执行步骤

1. 执行绑定命令：

openclaw smartpi accounts bind

2. 从输出中提取 绑定ID: 后的 bindingId。
3. 使用 bindingId 生成 smartpi_qr.png。
4. 把二维码图片发给用户，并提示：请用微信扫一扫，绑定成功后我会继续确认设备连接状态。
5. 等待 30-120 秒，检查日志中是否出现 WebSocket connected: <deviceKey>。
6. 连接成功后告知用户：设备已连接，可以对着 SmartPi 说话了。

二维码生成方式

优先使用当前环境已经安装的二维码工具，不要为了生成二维码自动安装依赖。

Python：

import qrcode
binding_id = "REPLACE_WITH_ACTUAL_BINDING_ID"
qrcode.make(binding_id).save("smartpi_qr.png")

Node.js：

node -e "const id=process.argv[1]; require('qrcode').toFile('smartpi_qr.png',id,{type:'png'},e=>e&&console.error(e))" "REPLACE_WITH_ACTUAL_BINDING_ID"

成功判定

• 已生成二维码并发送给用户。
• 日志出现 WebSocket connected: <deviceKey>。
• openclaw smartpi accounts list 能看到新设备。

失败分支

• 未提取到 bindingId：反馈绑定命令输出异常，并展示关键输出让用户确认。
• 二维码生成失败：说明当前环境缺少二维码依赖，询问用户是否允许安装依赖或改用其他方式生成。
• 120 秒内未连接：转入 流程：连接失败排查。
• 连接后仍不可用：转入 流程：9002 排查。

流程：查看设备

执行步骤

openclaw smartpi accounts list

输出要求

• 如果有设备，列出 deviceKey、在线状态或命令输出中的关键字段。
• 如果没有设备，提示用户可以执行绑定流程。
• 不要伪造设备状态；只根据命令输出和日志判断。

流程：删除设备

执行步骤

1. 先列出现有设备：

openclaw smartpi accounts list

2. 确认要删除的 deviceKey。
3. 明确提醒用户：删除会解绑本地记录，并可能同步解绑云端。
4. 用户确认后执行：

openclaw smartpi accounts remove <deviceKey>

5. 再次执行 accounts list 验证设备已删除。

安全规则

• 删除设备前必须获得用户明确确认。
• 如果用户没有提供 deviceKey，必须先列出设备并让用户选择。
• 不要批量删除设备，除非用户明确要求并逐项确认。

流程：首次安装或修复插件

目标

安装并启用 openclaw-smartpi 插件，确保 Gateway 能加载 SmartPi channel。

执行步骤

1. 检查插件状态：

openclaw plugins list

2. 若插件未安装，征得用户确认后执行：

openclaw plugins install openclaw-smartpi

3. 修改配置前，必须先读取完整配置。
4. 保留已有 plugins.allow 和 channels 内容，只追加 SmartPi 所需项。
5. 重启 Gateway 前说明影响，用户确认后执行：

openclaw gateway restart

6. 重启后再次检查 plugins list 和日志。

成功判定

• openclaw plugins list 显示 openclaw-smartpi: enabled。
• 配置中存在 channels.openclaw-smartpi。
• 日志中没有 cannot resolve agentId。

流程：连接失败排查

排查顺序

1. 检查插件是否启用：openclaw plugins list
2. 检查账号是否存在：openclaw smartpi accounts list
3. 检查日志是否出现 WebSocket connected
4. 检查日志是否出现 WebSocket disconnected
5. 检查网络、设备扫码是否完成、绑定是否过期。
6. 若日志出现 cannot resolve agentId，检查 channels.openclaw-smartpi。

输出要求

• 先说明当前卡在哪一层：插件、账号、WebSocket、路由、AI 响应。
• 每次只给用户一个明确下一步，不要同时抛出大量可能原因。

流程：9002 排查

9002 表示 AI 未在限定时间内回复。不要直接假设是设备坏了，应按链路排查。

排查顺序

1. 插件状态：openclaw plugins list，确认 openclaw-smartpi: enabled。
2. 设备绑定：openclaw smartpi accounts list，确认存在设备。
3. 设备连接：查日志 WebSocket connected，确认设备在线。
4. 路由配置：查日志 cannot resolve agentId，确认 channels.openclaw-smartpi 存在。
5. AI 响应：向 OpenClaw 发一条文本，确认本地模型、MCP、Tools 是否响应过慢。
6. 超时日志：查 AI response timeout，判断是否由模型慢、MCP 阻塞或工具调用卡住导致。

常见结论

• 插件未启用：修复插件安装或配置。
• 没有绑定设备：引导用户走绑定流程。
• WebSocket 未连接：检查扫码、网络和绑定状态。
• cannot resolve agentId：修复 channels.openclaw-smartpi。
• 文本请求也慢：优先排查本地模型、MCP、Tools，而不是 SmartPi 设备。

硬性规则

plugins.allow 是整体替换

config.patch 对数组是整体替换，不是追加。修改前必须先读取当前完整配置，构造包含原有插件和 openclaw-smartpi 的完整数组后再 patch。

channels 是整体替换

不要只 patch channels.openclaw-smartpi。这可能覆盖掉已有 channel，例如 discord、telegram。必须保留所有已有 channels，再追加 openclaw-smartpi。

channel.id 必须匹配

插件内部 channel.id = "openclaw-smartpi"，配置中必须是 channels.openclaw-smartpi，一字不差。否则消息无法路由，常见日志为 cannot resolve agentId。

配置示例

{
  "channels": {
    "openclaw-smartpi": {
      "enabled": true,
      "defaultAgentId": "main"
    }
  }
}

用户沟通规范

• 先说明动作：执行命令前，用一句话说明要检查什么。
• 展示关键结果：只摘取插件状态、设备 ID、日志关键字等必要信息。
• 区分事实和推测：没有日志证据时，不要断言设备在线或离线。
• 需要确认时暂停：安装、删除、重启、配置修改前必须等待用户确认。
• 失败时给下一步：不要只说失败，要说明下一步检查命令或需要用户提供的信息。

常用命令

命令	用途	风险
openclaw --help	检查 CLI 是否可用	只读
openclaw plugins list	确认插件状态	只读
openclaw smartpi accounts list	查看已绑定设备	只读
openclaw smartpi accounts bind	扫码绑定新设备	创建绑定
openclaw smartpi accounts remove <deviceKey>	删除设备并解绑	高风险
openclaw plugins install openclaw-smartpi	安装插件	修改环境
openclaw gateway restart	重启 Gateway	中断服务

日志关键字

关键字	含义	下一步
WebSocket connected	设备已上线	验证设备列表和语音交互
WebSocket disconnected	设备断开	检查网络、设备状态、绑定状态
cannot resolve agentId	缺少或错误配置 channels.openclaw-smartpi	修复 channels 配置
AI response timeout	AI 响应超时，可能导致 9002	排查模型、MCP、Tools 响应链路

最小完成标准

每次使用本 Skill 后，最终回复必须包含：

• 当前状态：已绑定、已连接、未连接、未安装、配置异常或超时。
• 证据来源：命令输出、日志关键字或用户提供的信息。
• 下一步：如果未解决，明确下一条建议动作。