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

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

## 当前架构

- HarborForge Monitor Backend 提供服务器注册与遥测接收接口
- OpenClaw Gateway 加载 `harbor-forge` 插件
- 旧 sidecar (`server/telemetry.mjs`) 已移除
- 插件通过 Gateway/runtime 路径直接提供 OpenClaw 元数据
- Monitor 可选通过本地 `monitor_port` 桥接读取补充信息

## 当前后端接口

### 公开接口
- `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`: 远程服务器上的 `harbor-forge` 插件版本

## 已废弃内容

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

- 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. 如需本地桥接补充信息，配置 `monitor_port`
5. 重启 OpenClaw Gateway
6. 插件直接参与遥测链路；若本地桥接可达，则额外提供 OpenClaw 补充元数据

## 备注

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