# OpenClaw 实时状态显示器 - 公开版接口与架构说明

> 这是一份公开版协议说明。示例地址、IP、路径和凭据均已泛化。

## 总体架构

```text
OpenClaw 后台状态
        ↓
云端状态服务 FastAPI
        ↓
服务器端渲染 128x296 黑白位图
        ↓
ESP32-S3 通过 Wi-Fi 拉取
        ↓
Waveshare 2.9 寸电子墨水屏显示
```

## 主要接口

### 健康检查

```text
GET /health
```

用于确认云端状态服务是否正常运行。

### 模拟状态

```text
GET /status
POST /status/demo/{state}
```

用于早期测试。可模拟空闲、运行中、工具调用、异常、完成等状态。

### 真实 OpenClaw 状态

```text
GET /status/openclaw
POST /status/openclaw/refresh
```

云端服务从 OpenClaw 运行状态中提取任务、模型、上下文、token 等信息，并映射成屏幕需要的状态。

### 用户友好活动状态

```text
GET /status/activity
```

将内部事件映射成更容易理解的中文状态，例如：

- 已接收
- 操作执行中
- 工具调用完成
- 资料查询中
- 资料查询完成
- 整理中
- 已回复
- 空闲

### 屏幕原始帧

```text
GET /frame/activity.raw
```

返回 128x296 的 1-bit 原始 framebuffer，大小为 4736 字节。ESP32 下载后直接刷新到电子墨水屏。

ESP32 可以附带设备状态：

```text
GET /frame/activity.raw?device=esp32s3&wifi=1&rssi=-55&ip=LAN_IP
```

云端用这些信息生成屏幕右上角的 Wi-Fi 图标。

## ESP32 配置示例

实际使用时，需要在 ESP32 上放一个本地配置文件。不要把真实 Wi-Fi 名称和密码提交到公开仓库。

```python
WIFI_SSID = "YOUR_WIFI_NAME"
WIFI_PASSWORD = "YOUR_WIFI_PASSWORD"
STATUS_URL = "http://YOUR_SERVER_HOST:8787/status"
FRAME_URL = "http://YOUR_SERVER_HOST:8787/frame/activity.raw"

REFRESH_INTERVAL_S = 3
MAX_REFRESHES = 0
DEVICE_NAME = "esp32s3"
```

## 屏幕显示字段

当前屏幕主要显示：

- 品牌栏：OPENCLAW
- Wi-Fi 图标：来自 ESP32 回传的联网状态
- 主状态：从当前活动状态简化而来
- 前序动作：上一阶段动作
- 任务信息：模型、本轮 token、上下文比例、更新时间
- 耗时：运行中显示已用时间，完成后显示总耗时
- 底部统计：今日任务数、今日累计 token

## 刷新策略

ESP32 每隔数秒访问云端帧接口。只有下载到的新画面和上一帧不同，才会刷新电子墨水屏。

这样既能及时反映后台状态变化，又能避免电子墨水屏在内容未变化时频繁闪烁。

## 安全注意

公开资料中不应包含：

- 真实 Wi-Fi 名称和密码
- 真实公网 IP
- 内网 IP
- 服务器用户和绝对路径
- OpenClaw 会话原始日志
- API Key、Token、Cookie

发布前应对资料包和代码仓库做一次敏感信息扫描。