openclaw-smartpi

SKILL.md

---
name: smartpi
description: SmartPi 设备绑定、扫码、设备管理与连接故障排查。Use when the user mentions binding SmartPi, SmartPi QR code, 9002, SmartPi connection failure, listing SmartPi devices, or removing a SmartPi device.
allowed-tools: terminal, read_file, grep, find_path
context: local-first
---

# 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` 返回设备列表 |
| 查询设备连接状态 | [流程：查询设备连接状态](#流程查询设备连接状态) | `accounts status` 返回设备在线/离线状态 |
| 删除设备 | [流程：删除设备](#流程删除设备) | 删除命令成功且列表不再包含该设备 |
| 安装/启用插件 | [流程：首次安装或修复插件](#流程首次安装或修复插件) | `plugins list` 显示 `openclaw-smartpi: enabled` |
| 9002/超时 | [流程：9002 排查](#流程9002-排查) | 定位为连接、路由或 AI 响应链路问题 |

## 执行前检查

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

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

## 流程：绑定设备

### 目标

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

### 执行步骤

1. 执行绑定命令：

```bash
openclaw smartpi accounts bind
```

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

### 二维码生成方式

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

Python：

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

Node.js：

```bash
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 排查](#流程9002-排查)。

## 流程：查看设备

### 执行步骤

```bash
openclaw smartpi accounts list
```

### 输出要求

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

## 流程：查询设备连接状态

### 目标

通过设备号查询指定设备的在线/离线连接状态。

### 执行步骤

1. 如果用户未提供设备号，先执行 `openclaw smartpi accounts list` 列出所有设备供用户选择。
2. 获取设备号后，执行：

```bash
openclaw smartpi accounts status <device_number>
```

### 输出要求

- 根据命令输出，展示该设备的连接状态（在线/离线/未找到等）。
- 如果设备未找到，提醒用户检查设备号是否正确。
- 不要伪造状态；只根据命令输出和日志判断。

### 成功判定

- 命令返回设备连接状态（connected / disconnected / unknown 等）。
- 结合日志关键字进一步判断设备是否正常通信。

### 失败分支

- **设备未找到**：提示用户检查设备号是否正确，可重新执行 `accounts list` 确认。
- **命令执行失败**：展示错误信息，询问用户是否继续排查。

## 流程：删除设备

### 执行步骤

1. 先列出现有设备：

```bash
openclaw smartpi accounts list
```

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

```bash
openclaw smartpi accounts remove <deviceKey>
```

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

### 安全规则

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

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

### 目标

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

### 执行步骤

1. 检查插件状态：

```bash
openclaw plugins list
```

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

```bash
openclaw plugins install openclaw-smartpi
```

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

```bash
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`。

### 配置示例

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

## 用户沟通规范

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

## 常用命令

| 命令 | 用途 | 风险 |
| --- | --- | --- |
| `openclaw --help` | 检查 CLI 是否可用 | 只读 |
| `openclaw plugins list` | 确认插件状态 | 只读 |
| `openclaw smartpi accounts list` | 查看已绑定设备 | 只读 |
| `openclaw smartpi accounts status <device_number>` | 查询指定设备连接状态 | 只读 |
| `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 后，最终回复必须包含：

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