外观
稳定性手册
OpenClaw 作为自动化工具，稳定性优先级高于功能数量。稳定性验收应覆盖失败解释、重试证据、配置迁移和交付状态清理。
稳定性红线
| 红线 | 解释 |
|---|---|
| 错误分层 | 错误提示应标明失败层级，避免只显示“任务失败” |
| 基于证据重试 | 重试前读取日志、截图、状态或返回体 |
| 交付清理 | API Key、Token、授权码、OAuth 文件必须清理 |
| 策略校验 | 桌面点击、输入、微信发送必须走 Bridge policy |
| 状态来源明确 | 截图、授权、在线状态必须来自真实环境或标注为占位 |
稳定性验收应同时验证成功路径、失败提示和可执行的排查入口。
连接可靠性
手机和桌面连接都建议做成四段式：
text
发现 -> 认证 -> 健康检查 -> 能力探测| 阶段 | 手机控制 | 桌面 RPA |
|---|---|---|
| 发现 | Phone URL、设备列表、短码配对 | agents 目录、组件 manifest |
| 认证 | Token、Lumi Signature | Bridge Token、sidecar token |
| 健康检查 | /api/device/status | /api/desktop-agent/status、/health |
| 能力探测 | 截图、节点树、录屏、无障碍 | 截图、未读、点击输入策略 |
日志分层
| 日志 | 关注点 |
|---|---|
| 启动器 UI toast | 给用户的短提示 |
| 服务 / CLI 输出 | 当前命令、进程、端口、退出码 |
| Python Bridge 日志 | API 请求、授权、进程管理、桌面代理 |
| 手机执行日志 | 签名、截图、任务轮次、超时 |
| 打包日志 | 清理、拷贝、版本、校验、SHA256 |
重试策略
推荐三次以内的聚焦重试：
- 第一次失败：读取错误体和当前状态。
- 第二次失败：缩小动作，只做只读检查。
- 第三次失败：换证据来源，例如截图、health、端口、日志。
如果三次聚焦重试仍未恢复，应先把错误归类到授权、网络、设备、运行时、脚本或打包层，再决定下一步处理方式。
manifest 多源与缓存
在线包建议使用：
text
primary manifest
backup manifest
local cached manifest
local cached artifact
manual artifact path每个下载项至少包含：
json
{
"name": "luminode-desktop",
"version": "1.0.0",
"url": "https://example.com/luminode-desktop.zip",
"sha256": "..."
}文档中仅记录已部署的正式 CDN 地址。未确认的下载源可标记为“生产源待确认”，确认前不要写进面向用户的页面。
运行时健康指标
启动核心服务能在预期时间内启动并返回状态。
授权受保护能力能正确放行或明确拒绝。
设备手机和桌面组件能返回 health 与截图。
交付新目录、新机器、新用户状态下可复现。
自动化工具的合格标准
- 只读任务可以稳定完成。
- 写操作默认需要确认。
- 每个失败都有可读错误和下一步建议。
- 配置集中，路径不污染用户视野。
- 打包脚本能检查关键模板和运行时层。
- 文档能让新机器复现一次核心流程。
定时任务稳定性
定时任务应被当作生产链路处理，而不是把一次性按钮套上计时器。
| 机制 | 要求 |
|---|---|
| 任务定义 | 模板、参数、最大执行时间和停止条件必须可见 |
| 执行窗口 | 每类任务有独立超时，广告等待类不复用普通短任务超时 |
| 冷却时间 | 发布、曝光、擦亮等动作要限制频率 |
| 幂等保护 | 已完成、已发布、已领取时停止，不重复点击 |
| 留证 | 每次定时执行保存开始截图、结束截图和错误摘要 |
| 恢复 | 启动器重启后能恢复待执行队列，不重复执行已完成任务 |
如果任务涉及平台规则或账号状态，默认先跑观察模板；只有观察结果满足条件，才进入真实执行模板。