Roborock CLI — Agent 操作手册
本 skill 指导你（OpenClaw）如何安装和使用 roborock-cli 来控制石头扫地机。
所有命令输出格式化 JSON，可直接用 jq 解析。
前置检查（每次操作前）
用户想做什么？
├─ 安装 roborock-cli → §1 安装流程
├─ 首次使用 / 认证问题 → §2 认证流程
├─ 查询设备信息 → §3 查询命令
├─ 控制扫地机 → §4 控制命令
├─ 故障排除 → §5 错误处理
└─ 编写自动化脚本 → §6 脚本集成
§1 安装流程
1.1 检查 uv 是否已安装
uv --version
- 成功：输出版本号 → 跳到 1.3
- 失败：
command not found → 执行 1.2
1.2 安装 uv
macOS / Linux：
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
安装后验证：uv --version
1.3 安装 roborock-cli
uv tool install roborock-cli
验证：
roborock-cli --version
- 成功：输出
roborock-cli x.y.z
- 失败（Windows
os error 4551）：→ §5.4
1.4 更新
uv tool upgrade roborock-cli
1.5 卸载
uv tool uninstall roborock-cli
rm -rf ~/.cache/roborock-cli/ # 清理认证和缓存
§2 认证流程
认证是所有其他命令的前置条件。认证信息保存在 ~/.cache/roborock-cli/user_data.json。
2.1 执行认证
roborock-cli auth
要求：必须在交互式 TTY 终端执行（不支持管道/非交互环境）。
流程：
- 运行
roborock-cli auth，提示用户输入 Roborock 账号邮箱
- 等待用户输入邮件中收到的验证码
- 认证信息自动保存
- 账号邮箱可以在Roborock APP中查看、设置和修改"
⚠️ 重要：避免重复运行 roborock-cli auth
每次运行 roborock-cli auth 都会发送新的验证码，导致之前的验证码立即失效。正确做法：
- 只运行一次
roborock-cli auth，然后等待用户提供验证码
- 如果验证码输入后验证失败，先询问用户："验证失败，是否需要重新发送验证码？"
- 只有用户确认同意后，才再次运行
roborock-cli auth
- 绝对不要在用户还没输入验证码时就重新运行
roborock-cli auth
2.2 验证认证是否有效
roborock-cli devices
- 成功：输出设备 JSON → 认证有效
- 失败（exit_code=2）：认证过期 → 重新执行
roborock-cli auth
§3 查询命令
查询命令不改变设备状态，可安全执行。
命令总览
| 命令 | 用途 | 关键输出 |
|---|
devices | 列出设备 | devices[].name → -d 参数 |
status -d DEV | 设备状态 | rooms[].segment_id → start-clean -s |
routines -d DEV | 智能场景 | routines[].id → execute-routine |
map -d DEV | 地图信息 | 位置坐标、可选保存 PNG |
数据流（命令间依赖）
devices → name ──────────────────────► 所有命令的 -d 参数（模糊匹配）
status → rooms[].segment_id ───────► start-clean -s（指定房间）
status → dnd_enabled/start/end ────► set-dnd（修改勿扰）
status → volume.value ────────────► set-volume（修改音量）
routines → routines[].id ──────────► execute-routine（执行场景）
设备选择规则（-d 参数）
- 单设备：可省略
-d，自动选择
- 多设备：必须指定
-d，否则报 exit_code=4（ParamError）
- 匹配方式：子串匹配，不区分大小写（
-d 客厅 匹配 "客厅扫地机"）
典型查询序列
# 1. 获取设备名
roborock-cli devices | jq '.devices[].name'
# 2. 获取设备状态（含房间列表）
roborock-cli status -d "设备名" | jq '.rooms.value'
# 3. 获取场景列表
roborock-cli routines -d "设备名" | jq '.routines[]'
完整的命令参数和输出字段规格，参见 references/commands.md。
§4 控制命令
所有控制命令成功返回 {"status": "ok", ...}。执行前应确认设备状态。
决策树：用户想控制什么？
用户意图
├─ 清洁
│ ├─ 全屋清洁 → start-clean
│ ├─ 指定房间 → 先 status 获取 segment_id → start-clean -s ID [-r N]
│ ├─ 暂停 → pause-clean
│ ├─ 恢复 → resume-clean
│ └─ 停止 → stop-clean
├─ 回充电座 → go-home
├─ 基座操作
│ ├─ 集尘 → dock-action start_collect_dust / stop_collect_dust
│ └─ 洗拖布 → dock-action start_wash / stop_wash
├─ 声音与勿扰
│ ├─ 调节音量 → set-volume N（0-100）
│ ├─ 发声寻找机器人 → find-robot（让机器人发出"滴滴"声，不返回坐标）
│ └─ 勿扰模式 → set-dnd enable --start HH:MM --end HH:MM / set-dnd disable
└─ 场景 → 先 routines 获取 id → execute-routine ID
控制前检查模式
在执行控制命令前，建议先检查设备状态：
# 检查设备是否空闲
STATE=$(roborock-cli status -d "设备名" | jq -r '.state.value')
# state=charging / idle → 可以开始清洁
# state=cleaning → 正在清洁中
# state=error → 有错误，检查 error_code
指定房间清洁完整流程
# 1. 获取房间 segment_id
roborock-cli status -d "设备名" | jq '.rooms.value[] | "\(.segment_id) → \(.name)"'
# 2. 执行清洁（segment_id=16，清洁 2 遍）
roborock-cli start-clean -d "设备名" -s 16 -r 2
# 3. 验证已开始
roborock-cli status -d "设备名" | jq '.state.value'
# 期望输出: "cleaning"
完整的命令参数规格，参见 references/commands.md。
§5 错误处理
退出码速查
| 退出码 | 含义 | 恢复动作 |
|---|
| 0 | 成功 | — |
| 1 | 通用错误（连接超时等） | 检查网络 → 重试 |
| 2 | 认证错误 | roborock-cli auth 重新认证 |
| 3 | 设备错误 | roborock-cli devices 确认设备名 |
| 4 | 参数无效 | 检查参数范围（音量 0-100、时间 HH:MM） |
| 5 | 内部错误 | 报告给用户 |
| 130 | 用户中断 | Ctrl+C，无需处理 |
错误输出格式：{"error": "描述", "exit_code": N}
5.1 连接超时（exit_code=1）
{"error": "连接超时（30.0秒）", "exit_code": 1}
排查步骤：
- 确认网络连接正常
- 确认设备在线（通过 Roborock App）
- 重试命令
5.2 认证过期（exit_code=2）
roborock-cli auth # 重新认证即可
5.3 API 频率限制（9002 错误）
Roborock API 限制 get_home_data 调用 5 次/小时、40 次/天。
诊断：
ls -la ~/.cache/roborock-cli/device_cache.pkl
# 正常 ~3KB，0 字节说明缓存写入失败
修复：
rm ~/.cache/roborock-cli/device_cache.pkl
roborock-cli devices # 重建缓存
5.4 Windows os error 4551
Windows 安全策略阻止 uv 缓存目录下的 Python 解释器。
修复方法 1（推荐）：
uv cache clean
uv tool install roborock-cli
修复方法 2：
uv tool install --python python3.12 roborock-cli
§6 脚本集成
退出码检查
if roborock-cli start-clean -s 16 >/dev/null; then
echo "清洁已启动"
else
echo "启动失败，退出码: $?"
fi
注意：roborock-cli 的正常输出和错误 JSON 都输出到 stdout，不输出到 stderr。抑制输出用 >/dev/null，不是 2>/dev/null。
JSON 输出解析
所有正常输出为格式化 JSON（indent=2, ensure_ascii=False），可用 jq 处理：
# 获取电池电量
roborock-cli status -d "设备名" | jq '.battery.value'
# 获取所有房间名和 ID
roborock-cli status -d "设备名" | jq '.rooms.value[] | {name, segment_id}'
# 获取场景 ID 和名称
roborock-cli routines -d "设备名" | jq '.routines[] | "\(.id) → \(.name)"'
环境变量
| 变量 | 默认值 | 说明 |
|---|
ROBOROCK_AUTH_CACHE | ~/.cache/roborock-cli/user_data.json | 认证缓存路径 |
ROBOROCK_DEVICE_CACHE | ~/.cache/roborock-cli/device_cache.pkl | 设备缓存路径 |
V1 协议要求
除 auth 和 devices 外，所有命令要求设备支持 V1 协议。不支持时返回 exit_code=3。绝大多数近年 Roborock 设备均支持。
参考资料
- 完整命令规格（参数、输出字段、示例）：读取
references/commands.md
- 需要某个命令的详细参数或输出字段时，读取该文件的对应章节
