HarborForge.Backend/docs/OPENCLAW_PLUGIN_DEV_PLAN.md

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 运行时逻辑。