Roborock Local Server 是一个把石头（Roborock）扫地机的云端 HTTPS 和 MQTT 服务搬到家庭局域网的本地模拟服务器，而 Onboarding 配对是其中最关键的一步：让你的扫地机"改头换面"，不再连接官方云，转而直连你自己搭建的本地服务器。本教程带你用 8 步完成 Roborock 本地服务器配对——即使是一台从未注册过官方云的全新机器，也能通过"盲配"（blind onboarding）成功接入。

📌 前置条件：请已完成 安装流程，服务器已能在api-...主机名下访问，并且已经做完云端导入（cloud import / fetch-data）步骤。参考 docs/installation.md 和 docs/onboarding.md。

一、配对前检查清单

开始之前，确认以下条件全部满足：

💡 如果是全新机器：建议先用官方 Roborock App 完成一次初始设置（让 App 拉取机器元数据），但不要升级固件，除非你确认最新固件受支持。

二、选择一种配对方式

Roborock Local Server 提供三种 Onboarding 方式，任选其一：

1. 命令行 CLI—— 运行 start_onboarding.py，适合习惯终端的用户；
2. 浏览器 Web UI—— 运行 start_onboarding_gui.py，自动打开图形界面，新手推荐 ⭐；
3. 手机 App（LocalRock）—— 用第三方应用 LocalRock（Android / iOS）直接在手机上配对，无需第二台电脑。

三者底层流程完全一致，只是界面不同。

三、第 1~2 步：启动配对工具并登录

在第二台电脑上（可以从仓库检出目录直接运行），执行：

uv run start_onboarding.py --server api-roborock.example.com

• --server填你安装时用的api-...主机名；自定义端口要写成api-roborock.example.com:8443的形式，省略端口时默认555。
• 如果你不想用终端，改用 GUI 版：uv run start_onboarding_gui.py，浏览器会自动打开配置页，所有参数在表单里填写即可。

⚠️ 注意：最终发给扫地机的host[:port]/值（去掉api-前缀后）有32 字符的硬上限，主机名越短越安全，例如rr.example.com:555/可以，roborock-local-server.example.com:555/就超长了。

启动后，CLI 会先要求输入本地服务器的admin 密码（就是访问/admin后台的密码），登录成功后会列出可配对的扫地机清单，每台设备后面带有状态标签，例如：

Qrevo MaxV [Public Key Determined] [Disconnected]

四、第 3 步：选择扫地机（全新机器选 New vacuum 盲配）

• 普通设备：直接从列表里选你的机器即可。
• 全新机器（从未上过云）：它没有云端库存记录，不会出现在列表里。此时在设备选择步骤选择New vacuum选项（CLI 中输入new，GUI 里是已导入设备下方的 New vacuum 按钮），开启"盲配"会话。

盲配的原理很简单：不指定目标设备，服务器直接接收配对流量里出现的第一台扫地机身份（did），由服务器签发localKey。设备走到 NC Prepare 并注册后，服务器会自动把它加入设备清单，之后就和普通设备一样出现在后台和 Home Assistant 里。V1、V2 协议机型均支持。

五、第 4 步：填写家庭 Wi-Fi 与时区参数

脚本会提示你补全缺失的信息（也可以在命令行一次性传参，省得反复输入）：

💡 好消息：如果填的时区在脚本内置表里（美、欧、日、悉尼等主流时区都覆盖了），cst和country-domain会自动推导，不用手填。中国时区Asia/Shanghai对应的 POSIX 串是CST-8。

uv run start_onboarding.py --server api-roborock.example.com \ --ssid "My Wifi" --password "Password123" \ --timezone "Asia/Shanghai" --country-domain cn

六、第 5 步：重置扫地机 Wi-Fi 并连接热点

这一步需要物理操作：

1. 长按底座上的两个按键（或机身左右按键）3~5 秒，听到 Wi-Fi 重置提示音后松手；
2. 在第二台电脑上连接扫地机发出的临时 Wi-Fi 热点；
3. 回到脚本按下 Enter（GUI 则点击 "Send onboarding packet"）。

🔑 关键区分：做的是Wi-Fi 重置，不是完整恢复出厂！如果你不确定自己机型的重置方法，搜索该型号的具体步骤。这一步是整个流程中唯一需要动手的环节。

脚本随后会把cfgwifi配对数据包发送到扫地机的192.168.8.1，告诉它"回家的 Wi-Fi 叫这个名字，密码是这个，云端地址指向我的本地服务器"。

七、第 6 步：切回家庭 Wi-Fi，等待自动轮询

发送成功后，把电脑切回正常家庭 Wi-Fi。接下来工具会自动接管：

• 等待主服务器重新可达（GUI 最长等 2 分钟，已知在线可点 "I'm back online, skip the wait" 跳过）；
• 每 5 秒轮询一次，最长 5 分钟，观察三项进展：query 样本数是否增长、公钥是否恢复（Public Key determined）、设备是否连上 MQTT；
• 全程有实时日志窗口（GUI 下方 log pane / CLI 终端输出），不用再盯着管理后台看。

八、第 7~8 步：确认结果，必要时多跑一轮

公钥恢复可能需要几分钟，部分新机型在恢复期间 query 样本数会一直是 0，盯住 Public Key determined 状态即可。脚本会明确告诉你下一步该retry、wait、换设备还是结束：

• 首轮成功通常表现为 query 样本数上涨；
• 样本涨了但公钥还没恢复 → 再跑一轮完整配对循环；
• 公钥就绪后 → 脚本会提示你做最后一轮配对让设备完全连上；
• 有些机器总共需要2~4 轮，最后一轮也可能慢几分钟才显示 Wi-Fi connected，耐心等即可。

🎉 当脚本报告扫地机已连接本地服务器时，Onboarding 就全部完成了。Home Assistant 的设备列表此时也能看到它。想随时撤销？再做一次 Wi-Fi 重置，机器就回到出厂配对状态，整个过程可逆。

九、手机端替代方案：用 LocalRock 盲配

如果没有第二台电脑，可以用开源应用LocalRock（Android / iOS）直接在手机上完成配对：

1. 在 App 中填入本地服务器地址和管理凭据，完成连接；
2. 选择Add vacuum；
3. 长按按键 3~5 秒重置扫地机 Wi-Fi；
4. 按 App 指引让手机连上扫地机热点并发送家庭 Wi-Fi 凭据；
5. App 自动完成握手、公钥恢复，并验证扫地机已连上本地服务器。

详见 docs/roborock_app.md。

十、常见问题速查

小结

Roborock Local Server 的 Onboarding 配对可以概括为：启动工具 → 登录选机 → 填 Wi-Fi → 重置连热点 → 发送配对包 → 切回等轮询 → 多轮循环 → 完成。其中全新机器的 New vacuum 盲配选项，让从未上云的扫地机也能直接接入本地服务器，无需任何 Root、拆机或固件修改。

延伸阅读：

• 配对官方文档：docs/onboarding.md
• 安装与网络配置：docs/installation.md
• 配对入口脚本：start_onboarding.py、start_onboarding_gui.py、共享逻辑 onboarding_shared.py
• 已测机型兼容列表：docs/tested_vacuums.md
• Home Assistant 接入：docs/home_assistant.md