HarborForge.Backend/docs/openclaw-monitor-plugin-plan.md

OpenClaw Monitor Agent Plugin 开发计划（草案）

目标

让被监测服务器通过 WebSocket 主动接入 HarborForge Backend，并持续上报：

• OpenClaw 版本
• agent 列表
• 每 5 分钟主机指标（CPU/MEM/DISK/SWAP）
• agent 状态变更事件

握手流程

1. Admin 在 HarborForge 后台添加 server identifier
2. Admin 生成 challenge（10 分钟有效）
3. 插件请求 GET /monitor/public/server-public-key 获取公钥
4. 插件构造 payload：
   • identifier
   • challenge_uuid
   • nonce（随机）
   • ts（ISO8601）
5. 使用 RSA-OAEP(SHA256) 公钥加密，base64 后作为 encrypted_payload 发给 WS /monitor/server/ws
6. 握手成功后进入事件上报通道

插件事件协议

server.hello

{
  "event": "server.hello",
  "payload": {
    "openclaw_version": "x.y.z",
    "agents": [{"id": "a1", "name": "agent-1", "status": "idle"}]
  }
}

server.metrics（每 5 分钟）

{
  "event": "server.metrics",
  "payload": {
    "cpu_pct": 21.3,
    "mem_pct": 42.1,
    "disk_pct": 55.9,
    "swap_pct": 0.0,
    "agents": [{"id": "a1", "name": "agent-1", "status": "busy"}]
  }
}

agent.status_changed（可选）

{
  "event": "agent.status_changed",
  "payload": {
    "agents": [{"id": "a1", "name": "agent-1", "status": "focus"}]
  }
}

实施里程碑

• M1: Node/Python CLI 插件最小握手联通
• M2: 指标采集 + 周期上报
• M3: agent 状态采集与变更事件
• M4: 守护化（systemd）+ 断线重连 + 本地日志

风险与注意事项

• 时钟漂移会导致 ts 校验失败（建议 NTP）
• challenge 仅一次可用，重复使用会被拒绝
• nonce 重放会被拒绝
• 需要保证插件本地安全保存 identifier/challenge（短期）