# OpenClaw 实时状态显示器 - 公开版开发过程摘要

> 这是一份适合公开发布的开发过程摘要。它保留关键过程和踩坑经验，移除了个人网络、服务器 IP、内部路径等敏感信息。

## 一句话总结

这个项目是一次“现实反馈 + AI 工程实现”的协作开发：我负责接线、拍照、观察屏幕和提出体验要求，Codex 负责查方案、写程序、调驱动、部署服务和优化界面。

## 关键阶段

### 阶段一：确认硬件

使用的硬件是：

- ESP32-S3 N16R8 开发板
- Waveshare 2.9 寸黑白电子墨水屏
- 随屏幕附带的杜邦线

最初需要确认三件事：

1. 板子是否能被电脑识别
2. MicroPython 是否能正常烧录和运行
3. 屏幕接线是否正确

### 阶段二：点亮屏幕

第一次真正的挑战是屏幕驱动。

早期遇到的问题包括：

- 屏幕无显示
- 画面上下颠倒
- 画面左右镜像
- 字母像照镜子一样反着
- 内容方向和 PCB 丝印方向不一致

解决方式是逐步调整：

- 屏幕初始化序列
- framebuffer 位序
- 屏幕扫描方向
- 最终输出方向旋转

这个阶段最典型的协作方式是：我拍照反馈屏幕现在长什么样，Codex 根据画面判断是旋转、镜像还是底层扫描方向问题，然后继续调整代码。

### 阶段三：从 demo 到真实状态

点亮屏幕后，最初只能显示 demo 状态。下一步是让它真正显示 OpenClaw 后台状态。

最终架构是：

```text
OpenClaw 后台
  -> 云端 FastAPI 状态服务
  -> ESP32 通过 Wi-Fi 轮询
  -> 电子墨水屏显示
```

ESP32 不是靠 USB 数据线实时通信，而是像一个独立小设备一样，通过 Wi-Fi 主动访问云端服务。

### 阶段四：中文界面

MicroPython 自带显示能力更适合英文和简单字符，中文显示会增加很多复杂度。

最终方案是：

- 云端服务器使用 Python/Pillow 渲染中文界面
- 输出 128x296 的 1-bit 原始屏幕帧
- ESP32 下载这张原始帧并刷新到电子墨水屏

这样中文排版、字体和界面布局都在服务器端处理，ESP32 端逻辑更简单。

### 阶段五：界面打磨

界面经历了十几轮迭代，主要调整包括：

- 从英文调试信息改为中文用户语言
- 将“当前状态”和“说明”合并成一个状态模块
- 增加“前序”动作，让任务推进更连续
- 规范状态文案，例如把“刚刚回复完”改成“已回复”
- 增加 Wi-Fi 图标
- 增加模型、本轮 token、上下文比例
- 增加今日任务数和今日 token
- 增加运行中已用时间和完成耗时

### 阶段六：刷新策略

电子墨水屏不适合频繁全屏刷新，所以最终策略是：

- ESP32 每 3 秒检查一次云端画面
- 如果画面内容没有变化，就不刷新屏幕
- 运行中耗时采用粗粒度显示，避免秒级变化触发频繁刷新
- 局部刷新做过预研，但当前稳定版仍使用“有变化才全刷”

## 关键收获

这个项目最有意思的地方不是技术本身有多复杂，而是协作方式发生了变化：

- 我不需要一开始就懂电子墨水屏驱动
- 我可以先描述需求和现象
- Codex 根据反馈完成工程实现
- 我再根据真实硬件表现继续反馈

这让一个原本对硬件小白来说门槛很高的项目，变成了一次可以不断试错、逐步收敛的协作过程。

## 当前限制

- 没有外壳
- 供电还不够优雅
- 显示内容还可以继续优化
- 安装和复刻流程还需要进一步整理

但作为一个原型，它已经能真实显示 OpenClaw 后台正在做什么。