# OpenClaw Plugin 开发计划（当前版）

**状态**: API Key 方案已落地，challenge / WebSocket 旧方案已废弃。

## 当前架构

- HarborForge Monitor Backend 提供服务器注册与遥测接收接口
- OpenClaw Gateway 加载 `harborforge-monitor` 插件
- 插件在 `gateway_start` 时启动 sidecar (`server/telemetry.mjs`)
- sidecar 通过 **HTTP + X-API-Key** 向 Backend 上报遥测

## 当前后端接口

### 公开接口
- `GET /monitor/public/overview`

### 管理接口
- `GET /monitor/admin/servers`
- `POST /monitor/admin/servers`
- `DELETE /monitor/admin/servers/{id}`
- `POST /monitor/admin/servers/{id}/api-key`
- `DELETE /monitor/admin/servers/{id}/api-key`

### 插件上报接口
- `POST /monitor/server/heartbeat-v2`
  - Header: `X-API-Key`
  - Body:
    - `identifier`
    - `openclaw_version`
    - `plugin_version`
    - `agents`
    - `cpu_pct`
    - `mem_pct`
    - `disk_pct`
    - `swap_pct`
    - `load_avg`
    - `uptime_seconds`

## 数据语义

- `openclaw_version`: 远程服务器上的 OpenClaw 版本
- `plugin_version`: 远程服务器上的 harborforge-monitor 插件版本

## 已废弃内容

以下旧方案已经废弃，不再作为实现路径：

- challenge UUID
- `GET /monitor/public/server-public-key`
- `POST /monitor/admin/servers/{id}/challenge`
- `WS /monitor/server/ws`
- challenge / nonce 握手逻辑

## 前端管理页要求

Monitor 管理页应提供：

- Add Server
- Generate API Key
- Revoke API Key
- Delete Server

不再提供 `Generate Challenge`。

## 运行流程

1. 管理员在 Monitor 中注册服务器
2. 管理员为服务器生成 API Key
3. 将 API Key 写入 `~/.openclaw/openclaw.json`
4. 重启 OpenClaw Gateway
5. 插件启动 sidecar
6. sidecar 定时向 `/monitor/server/heartbeat-v2` 上报

## 备注

当前保留了对旧 challenge 数据表的**删除兼容清理**（仅为兼容老数据库中的遗留数据），但不再保留 challenge 功能入口与运行时逻辑。