roborock-2014（机器人摇滚 2014）

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 终端执行（不支持管道/非交互环境）。

流程：

1. 运行 roborock-cli auth，提示用户输入 Roborock 账号邮箱
2. 等待用户输入邮件中收到的验证码
3. 认证信息自动保存

• 账号邮箱可以在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 → 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 错误处理

退出码速查

错误输出格式：{"error": "描述", "exit_code": N}

5.1 连接超时（exit_code=1）

{"error": "连接超时（30.0秒）", "exit_code": 1}

排查步骤：

1. 确认网络连接正常
2. 确认设备在线（通过 Roborock App）
3. 重试命令

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)"'

环境变量

V1 协议要求

除 auth 和 devices 外，所有命令要求设备支持 V1 协议。不支持时返回 exit_code=3。绝大多数近年 Roborock 设备均支持。

参考资料

• 完整命令规格（参数、输出字段、示例）：读取 references/commands.md
• 需要某个命令的详细参数或输出字段时，读取该文件的对应章节