# OpenClaw 实时状态显示器 - 公开版路线图

> 这是一份面向视频观众和复刻者的公开版路线图。原始开发日志中的个人 Wi-Fi、服务器 IP、内网地址、远端路径等信息已移除或泛化。

## 项目目标

做一个放在桌面上的 OpenClaw 后台状态小窗。

当 OpenClaw 执行一个需要几十秒到几分钟的任务时，飞书或聊天界面在最终回复前通常看不到过程。这个小硬件会显示 OpenClaw 当前是在接收任务、调用工具、查询资料、整理回复，还是已经完成。

## 硬件方案

- 开发板：ESP32-S3 N16R8
- 屏幕：Waveshare 2.9 inch e-Paper Module，黑白，SPI
- 连接：杜邦线
- 供电：USB 供电
- 通信：ESP32 通过 Wi-Fi 主动访问云端状态服务

## 接线表

| 墨水屏接口 | ESP32-S3 引脚 |
| --- | --- |
| VCC | 3V3 |
| GND | GND |
| DIN | GPIO11 |
| CLK | GPIO12 |
| CS | GPIO10 |
| DC | GPIO9 |
| RST | GPIO8 |
| BUSY | GPIO7 |

注意：接线和插拔建议断电操作。VCC 使用 3.3V，不要误接 5V。

## 实现路线

### 1. 点亮屏幕

- 搭建 MicroPython 环境
- 烧录 ESP32-S3 固件
- 移植 Waveshare 2.9 寸电子墨水屏驱动
- 完成 Hello World 显示
- 修正旋转、镜像、扫描方向和字节位序

### 2. 抽象显示逻辑

- 封装屏幕初始化
- 封装 framebuffer 处理
- 实现基础状态卡片布局
- 固化正确的屏幕显示方向

### 3. 建立云端状态服务

- 使用 FastAPI 提供状态接口
- 提供模拟状态接口用于早期调试
- 后续接入真实 OpenClaw 状态
- 使用 PM2 托管服务，保证云端常驻运行

### 4. ESP32 联网

- ESP32 连接 Wi-Fi
- 定时请求云端接口
- 下载状态数据或完整屏幕帧
- 判断内容变化，必要时刷新电子墨水屏

### 5. 中文显示方案

ESP32 上直接绘制中文比较麻烦，所以最终采用服务器端渲染：

```text
OpenClaw 状态
  -> 云端生成中文界面位图
  -> ESP32 下载 1-bit 原始帧
  -> 电子墨水屏显示
```

这样 ESP32 端只需要负责网络请求和屏幕刷新，中文排版、字体和布局都放在服务器端处理。

### 6. 产品化打磨

- 中文状态文案更用户友好
- 主状态和前序动作合并成连续任务流
- 加入 Wi-Fi 图标
- 加入模型、本轮 token、上下文比例和更新时间
- 加入今日任务数和今日累计 token
- 加入任务已用时间和完成耗时
- 将检查间隔优化到 3 秒
- 内容不变时跳过屏幕刷新，减少电子墨水屏频繁闪烁

## 当前状态

项目已经完成可用原型：

- ESP32 能独立联网
- 云端服务能读取 OpenClaw 状态
- 电子墨水屏能显示中文状态界面
- 状态变化可在真实任务中及时反映
- 云端服务已纳入 PM2 托管

## 后续计划

- 做外壳和支架
- 优化供电方式
- 整理更完整的复刻教程
- 评估局部刷新是否值得正式启用
- 按真实使用反馈继续调整屏幕显示内容