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

HarborForge Monitor / OpenClaw Plugin Connector Plan

目标

使用 API Key + HTTP heartbeat 连接 HarborForge Monitor 与远程 OpenClaw 节点。

认证方式

• 管理员为服务器生成 API Key
• 插件通过 X-API-Key 调用 heartbeat 接口
• 不再使用 challenge / RSA 公钥 / WebSocket 握手

上报接口

POST /monitor/server/heartbeat-v2

Headers

• X-API-Key: <server-api-key>

Payload

{
  "identifier": "vps.t1",
  "openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
  "plugin_version": "0.1.0",
  "agents": [
    { "id": "agent-bot1", "name": "agent-bot1", "status": "configured" }
  ],
  "cpu_pct": 12.3,
  "mem_pct": 45.6,
  "disk_pct": 78.9,
  "swap_pct": 0,
  "load_avg": [0.12, 0.08, 0.03],
  "uptime_seconds": 12345
}

语义

• openclaw_version: 远程主机上的 OpenClaw 版本
• plugin_version: harbor-forge 插件版本

插件生命周期

• 插件注册名为 harbor-forge
• 不再启动独立 server/telemetry.mjs sidecar
• 插件直接通过 Gateway/runtime 路径暴露 OpenClaw 元数据
• 如配置了 monitor_port，插件还可通过本地桥接与 HarborForge.Monitor 交互

配置位置

~/.openclaw/openclaw.json

{
  "plugins": {
    "entries": {
      "harbor-forge": {
        "enabled": true,
        "config": {
          "enabled": true,
          "backendUrl": "http://127.0.0.1:8000",
          "identifier": "vps.t1",
          "apiKey": "your-api-key",
          "monitor_port": 9100
        }
      }
    }
  }
}

已废弃

• challenge UUID
• server public key
• WebSocket telemetry
• encrypted handshake payload