Merge pull request 'feat: stabilize HarborForge monitor sidecar plugin' (#2) from feat/telemetry-sidecar-v2 into main

Reviewed-on: #2
2026-03-20 09:18:36 +00:00
parent 0debe835b4 14ed887ce3
commit afdbc469ad
14 changed files with 481 additions and 297 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1,5 @@
+plugin/node_modules/
+plugin/*.js
+plugin/*.js.map
+plugin/*.d.ts
+plugin/*.d.ts.map
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ HarborForge.OpenclawPlugin/
 │  └───────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────┘
                        │
-                        ▼ HTTP/WebSocket
+                        ▼ HTTP
              ┌─────────────────────┐
              │ HarborForge Monitor │
              └─────────────────────┘
@@ -76,21 +76,26 @@ node scripts/install.mjs --verbose

 ## 配置

-1. 在 HarborForge Monitor 中注册服务器，获取 `challengeUuid`
+1. 在 HarborForge Monitor 中注册服务器，并生成 `apiKey`

 2. 编辑 `~/.openclaw/openclaw.json`:

 ```json
 {
  "plugins": {
-    "harborforge-monitor": {
-      "enabled": true,
-      "backendUrl": "https://monitor.hangman-lab.top",
-      "identifier": "my-server-01",
-      "challengeUuid": "your-challenge-uuid-here",
-      "reportIntervalSec": 30,
-      "httpFallbackIntervalSec": 60,
-      "logLevel": "info"
+    "entries": {
+      "harborforge-monitor": {
+        "enabled": true,
+        "config": {
+          "enabled": true,
+          "backendUrl": "https://monitor.hangman-lab.top",
+          "identifier": "my-server-01",
+          "apiKey": "your-api-key-here",
+          "reportIntervalSec": 30,
+          "httpFallbackIntervalSec": 60,
+          "logLevel": "info"
+        }
+      }
    }
  }
 }
@@ -109,7 +114,7 @@ openclaw gateway restart
 | `enabled` | boolean | `true` | 是否启用插件 |
 | `backendUrl` | string | `https://monitor.hangman-lab.top` | Monitor 后端地址 |
 | `identifier` | string | 自动检测 hostname | 服务器标识符 |
-| `challengeUuid` | string | 必填 | 注册挑战 UUID |
+| `apiKey` | string | 必填 | HarborForge Monitor 生成的服务器 API Key |
 | `reportIntervalSec` | number | `30` | 报告间隔（秒） |
 | `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
 | `logLevel` | string | `"info"` | 日志级别: debug/info/warn/error |
@@ -151,7 +156,7 @@ npm run build

 ```bash
 cd server
-HF_MONITOR_CHALLENGE_UUID=test-uuid \
+HF_MONITOR_API_KEY=test-api-key \
 HF_MONITOR_BACKEND_URL=http://localhost:8000 \
 HF_MONITOR_LOG_LEVEL=debug \
 node telemetry.mjs
--- a/docs/monitor-server-connector-plan.md
+++ b/docs/monitor-server-connector-plan.md
@@ -1,112 +1,47 @@
-# HarborForge OpenClaw Server Connector Plugin — Project Plan
+# Monitor Server Connector Plan

-## 1) Goal
-Provide a secure, lightweight plugin/agent that connects servers to HarborForge Monitor, streams telemetry in real time, and falls back to HTTP heartbeat when WebSocket is unavailable.
+## Current design

-## 2) Scope
- **Handshake + auth** using backend-issued challenge + RSA-OAEP encrypted payload.
- **WebSocket telemetry** to `/monitor/server/ws`.
- **HTTP heartbeat** to `/monitor/server/heartbeat` as fallback.
- **System metrics**: CPU/Mem/Disk/Swap/Uptime/OpenClaw version/Agents list.
- **Retry & backoff**, offline handling, and minimal local state.
+The plugin uses:

-## 3) Non-Goals
- No UI in the plugin.
- No provider billing calls from plugin.
- No multi-tenant auth beyond challenge + server identifier.
+- **HTTP heartbeat** to `/monitor/server/heartbeat-v2`
+- **API Key authentication** via `X-API-Key`
+- **Gateway lifecycle hooks**: `gateway_start` / `gateway_stop`

-## 4) Architecture
-```
-plugin/
-  config/          # load config & secrets
-  crypto/          # RSA-OAEP encrypt/decrypt helpers
-  collector/       # system + openclaw metrics
-  transport/       # ws + http heartbeat
-  state/           # retry/backoff, last sent, cache
-  main.ts|py        # entry
-```
+## No longer used

-### 4.1 Config
- `backend_url`
- `identifier`
- `challenge_uuid`
- `report_interval_sec` (default: 20-30s)
- `http_fallback_interval_sec` (default: 60s)
- `log_level`
+The following design has been retired:

-### 4.2 Security
- Fetch public key: `GET /monitor/public/server-public-key`
- Encrypt payload with RSA-OAEP
- Include `nonce` + `ts` (UTC) to prevent replay
- **Challenge valid**: 10 minutes
- **Offline threshold**: 7 minutes
+- challenge UUID
+- RSA public key fetch
+- encrypted handshake payload
+- WebSocket telemetry

-## 5) Communication Flow
-### 5.1 Handshake (WS)
-1. Plugin reads `identifier + challenge_uuid`.
-2. Fetch RSA public key.
-3. Encrypt payload: `{identifier, challenge_uuid, nonce, ts}`.
-4. Connect WS `/monitor/server/ws` and send `encrypted_payload`.
-5. On success: begin periodic telemetry push.
+## Runtime flow

-### 5.2 Fallback (HTTP)
-If WS fails:
- POST telemetry to `/monitor/server/heartbeat` with same payload fields.
- Retry with exponential backoff (cap 5–10 min).
+1. Gateway loads `harborforge-monitor`
+2. Plugin reads config from OpenClaw plugin config
+3. On `gateway_start`, plugin launches `server/telemetry.mjs`
+4. Sidecar collects:
+   - system metrics
+   - OpenClaw version
+   - plugin version
+   - configured agents
+5. Sidecar posts telemetry to backend with `X-API-Key`

-## 6) Telemetry Schema (example)
-```
+## Payload
+
+```json
 {
-  identifier: "vps.t1",
-  openclaw_version: "x.y.z",
-  cpu_pct: 12.5,
-  mem_pct: 41.2,
-  disk_pct: 62.0,
-  swap_pct: 0.0,
-  agents: [ { id: "a1", name: "agent", status: "running" } ],
-  last_seen_at: "2026-03-11T21:00:00Z"
+  "identifier": "vps.t1",
+  "openclaw_version": "OpenClaw 2026.3.13 (61d171a)",
+  "plugin_version": "0.1.0",
+  "agents": [],
+  "cpu_pct": 10.5,
+  "mem_pct": 52.1,
+  "disk_pct": 81.0,
+  "swap_pct": 0.0,
+  "load_avg": [0.12, 0.09, 0.03],
+  "uptime_seconds": 12345
 }
 ```
-
-## 7) Reliability
- Automatic reconnect on WS drop
- HTTP fallback if WS unavailable > 2 intervals
- Exponential backoff on failures
- Local cache for last successful payload
-
-## 8) Deployment Options
- **Systemd service** (preferred for VPS)
- **Docker container** (optional)
- Single-binary build if using Go/Rust
-
-## 9) Milestones
-**M1 – POC (2–3 days)**
- CLI config loader + HTTP heartbeat
- See online + metrics in Monitor
-
-**M2 – WS realtime (2–3 days)**
- Full handshake + WS streaming
- Reconnect & fallback logic
-
-**M3 – Packaging (1–2 days)**
- systemd unit + sample config
- installation script
-
-**M4 – Hardening & Docs (1–2 days)**
- logging, metrics, docs
- troubleshooting guide
-
-## 10) Deliverables
- Plugin source
- Config template + systemd unit
- Integration docs
- Test script + example payloads
-
-## 11) Open Questions
- Preferred language (Go/Python/Node/Rust)?
- How to read OpenClaw agent list (API vs local state)?
- Required log format / retention?
-
---
-
-**Next step:** confirm preferred runtime (Go/Python/Node) and I will scaffold the project structure + first heartbeat implementation.
--- a/plugin/core/live-config.d.ts
+++ b/plugin/core/live-config.d.ts
@@ -0,0 +1,15 @@
+export interface HarborForgeMonitorConfig {
+    enabled?: boolean;
+    backendUrl?: string;
+    identifier?: string;
+    apiKey?: string;
+    reportIntervalSec?: number;
+    httpFallbackIntervalSec?: number;
+    logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+interface OpenClawPluginApiLike {
+    config?: Record<string, unknown>;
+}
+export declare function getLivePluginConfig(api: OpenClawPluginApiLike, fallback: HarborForgeMonitorConfig): HarborForgeMonitorConfig;
+export {};
+//# sourceMappingURL=live-config.d.ts.map
--- a/plugin/core/live-config.d.ts.map
+++ b/plugin/core/live-config.d.ts.map
@@ -0,0 +1 @@
+{"version":3,"file":"live-config.d.ts","sourceRoot":"","sources":["live-config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED,UAAU,qBAAqB;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,qBAAqB,EAC1B,QAAQ,EAAE,wBAAwB,GACjC,wBAAwB,CAqB1B"}
--- a/plugin/core/live-config.js
+++ b/plugin/core/live-config.js
@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLivePluginConfig = getLivePluginConfig;
+function getLivePluginConfig(api, fallback) {
+    const root = api.config || {};
+    const plugins = root.plugins || {};
+    const entries = plugins.entries || {};
+    const entry = entries['harborforge-monitor'] || {};
+    const cfg = entry.config || {};
+    if (Object.keys(cfg).length > 0 || Object.keys(entry).length > 0) {
+        return {
+            ...fallback,
+            ...cfg,
+            enabled: typeof cfg.enabled === 'boolean'
+                ? cfg.enabled
+                : typeof entry.enabled === 'boolean'
+                    ? entry.enabled
+                    : fallback.enabled,
+        };
+    }
+    return fallback;
+}
+//# sourceMappingURL=live-config.js.map
--- a/plugin/core/live-config.js.map
+++ b/plugin/core/live-config.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"live-config.js","sourceRoot":"","sources":["live-config.ts"],"names":[],"mappings":";;AAcA,kDAwBC;AAxBD,SAAgB,mBAAmB,CACjC,GAA0B,EAC1B,QAAkC;IAElC,MAAM,IAAI,GAAI,GAAG,CAAC,MAAkC,IAAI,EAAE,CAAC;IAC3D,MAAM,OAAO,GAAI,IAAI,CAAC,OAAmC,IAAI,EAAE,CAAC;IAChE,MAAM,OAAO,GAAI,OAAO,CAAC,OAAmC,IAAI,EAAE,CAAC;IACnE,MAAM,KAAK,GAAI,OAAO,CAAC,qBAAqB,CAA6B,IAAI,EAAE,CAAC;IAChF,MAAM,GAAG,GAAI,KAAK,CAAC,MAAkC,IAAI,EAAE,CAAC;IAE5D,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjE,OAAO;YACL,GAAG,QAAQ;YACX,GAAG,GAAG;YACN,OAAO,EACL,OAAO,GAAG,CAAC,OAAO,KAAK,SAAS;gBAC9B,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,SAAS;oBAClC,CAAC,CAAC,KAAK,CAAC,OAAO;oBACf,CAAC,CAAC,QAAQ,CAAC,OAAO;SACG,CAAC;IAChC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}
--- a/plugin/core/live-config.ts
+++ b/plugin/core/live-config.ts
@@ -0,0 +1,39 @@
+export interface HarborForgeMonitorConfig {
+  enabled?: boolean;
+  backendUrl?: string;
+  identifier?: string;
+  apiKey?: string;
+  reportIntervalSec?: number;
+  httpFallbackIntervalSec?: number;
+  logLevel?: 'debug' | 'info' | 'warn' | 'error';
+}
+
+interface OpenClawPluginApiLike {
+  config?: Record<string, unknown>;
+}
+
+export function getLivePluginConfig(
+  api: OpenClawPluginApiLike,
+  fallback: HarborForgeMonitorConfig
+): HarborForgeMonitorConfig {
+  const root = (api.config as Record<string, unknown>) || {};
+  const plugins = (root.plugins as Record<string, unknown>) || {};
+  const entries = (plugins.entries as Record<string, unknown>) || {};
+  const entry = (entries['harborforge-monitor'] as Record<string, unknown>) || {};
+  const cfg = (entry.config as Record<string, unknown>) || {};
+
+  if (Object.keys(cfg).length > 0 || Object.keys(entry).length > 0) {
+    return {
+      ...fallback,
+      ...cfg,
+      enabled:
+        typeof cfg.enabled === 'boolean'
+          ? cfg.enabled
+          : typeof entry.enabled === 'boolean'
+            ? entry.enabled
+            : fallback.enabled,
+    } as HarborForgeMonitorConfig;
+  }
+
+  return fallback;
+}
--- a/plugin/index.ts
+++ b/plugin/index.ts
@@ -1,25 +1,12 @@
 /**
 * HarborForge Monitor Plugin for OpenClaw
- * 
+ *
 * Manages sidecar lifecycle and provides monitor-related tools.
 */
 import { spawn } from 'child_process';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { join } from 'path';
 import { existsSync } from 'fs';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-interface PluginConfig {
-  enabled?: boolean;
-  backendUrl?: string;
-  identifier?: string;
-  challengeUuid?: string;
-  reportIntervalSec?: number;
-  httpFallbackIntervalSec?: number;
-  logLevel?: 'debug' | 'info' | 'warn' | 'error';
-}
+import { getLivePluginConfig, type HarborForgeMonitorConfig } from './core/live-config';

 interface PluginAPI {
  logger: {
@@ -29,150 +16,169 @@ interface PluginAPI {
    warn: (...args: any[]) => void;
  };
  version?: string;
-  isRunning?: () => boolean;
+  config?: Record<string, unknown>;
+  pluginConfig?: Record<string, unknown>;
  on: (event: string, handler: () => void) => void;
  registerTool: (factory: (ctx: any) => any) => void;
 }

-export default function register(api: PluginAPI, config: PluginConfig) {
-  const logger = api.logger || { 
-    info: (...args: any[]) => console.log('[HF-Monitor]', ...args),
-    error: (...args: any[]) => console.error('[HF-Monitor]', ...args),
-    debug: (...args: any[]) => console.debug('[HF-Monitor]', ...args),
-    warn: (...args: any[]) => console.warn('[HF-Monitor]', ...args),
-  };
-
-  if (!config?.enabled) {
-    logger.info('HarborForge Monitor plugin disabled');
-    return;
-  }
-
-  if (!config.challengeUuid) {
-    logger.error('Missing required config: challengeUuid');
-    logger.error('Please register server in HarborForge Monitor first');
-    return;
-  }
-
-  const serverPath = join(__dirname, '..', 'server', 'telemetry.mjs');
-  
-  if (!existsSync(serverPath)) {
-    logger.error('Telemetry server not found:', serverPath);
-    return;
-  }
-
-  let sidecar: ReturnType<typeof spawn> | null = null;
-
-  function startSidecar() {
-    if (sidecar) {
-      logger.debug('Sidecar already running');
-      return;
-    }
-
-    logger.info('Starting HarborForge Monitor telemetry server...');
-    
-    const env = {
-      ...process.env,
-      HF_MONITOR_BACKEND_URL: config.backendUrl || 'https://monitor.hangman-lab.top',
-      HF_MONITOR_IDENTIFIER: config.identifier || '',
-      HF_MONITOR_CHALLENGE_UUID: config.challengeUuid,
-      HF_MONITOR_REPORT_INTERVAL: String(config.reportIntervalSec || 30),
-      HF_MONITOR_HTTP_FALLBACK_INTERVAL: String(config.httpFallbackIntervalSec || 60),
-      HF_MONITOR_LOG_LEVEL: config.logLevel || 'info',
-      OPENCLAW_PATH: process.env.OPENCLAW_PATH || join(process.env.HOME || '/root', '.openclaw'),
-      OPENCLAW_VERSION: api.version || 'unknown',
+export default {
+  id: 'harborforge-monitor',
+  name: 'HarborForge Monitor',
+  register(api: PluginAPI) {
+    const logger = api.logger || {
+      info: (...args: any[]) => console.log('[HF-Monitor]', ...args),
+      error: (...args: any[]) => console.error('[HF-Monitor]', ...args),
+      debug: (...args: any[]) => console.debug('[HF-Monitor]', ...args),
+      warn: (...args: any[]) => console.warn('[HF-Monitor]', ...args),
    };

-    sidecar = spawn('node', [serverPath], {
-      env,
-      detached: false,
-      stdio: ['ignore', 'pipe', 'pipe']
-    });
+    const baseConfig: HarborForgeMonitorConfig = {
+      enabled: true,
+      backendUrl: 'https://monitor.hangman-lab.top',
+      identifier: '',
+      reportIntervalSec: 30,
+      httpFallbackIntervalSec: 60,
+      logLevel: 'info',
+      ...(api.pluginConfig || {}),
+    };

-    sidecar.stdout?.on('data', (data: Buffer) => {
-      logger.info('[telemetry]', data.toString().trim());
-    });
+    const serverPath = join(__dirname, 'server', 'telemetry.mjs');
+    let sidecar: ReturnType<typeof spawn> | null = null;

-    sidecar.stderr?.on('data', (data: Buffer) => {
-      logger.error('[telemetry]', data.toString().trim());
-    });
-
-    sidecar.on('exit', (code, signal) => {
-      logger.info(`Telemetry server exited (code: ${code}, signal: ${signal})`);
-      sidecar = null;
-    });
-
-    sidecar.on('error', (err: Error) => {
-      logger.error('Failed to start telemetry server:', err.message);
-      sidecar = null;
-    });
-
-    logger.info('Telemetry server started with PID:', sidecar.pid);
-  }
-
-  function stopSidecar() {
-    if (!sidecar) {
-      logger.debug('Telemetry server not running');
-      return;
+    function resolveConfig() {
+      return getLivePluginConfig(api, baseConfig);
    }

-    logger.info('Stopping HarborForge Monitor telemetry server...');
-    sidecar.kill('SIGTERM');
-    
-    const timeout = setTimeout(() => {
-      if (sidecar && !sidecar.killed) {
-        logger.warn('Telemetry server did not exit gracefully, forcing kill');
-        sidecar.kill('SIGKILL');
+    function startSidecar() {
+      const live = resolveConfig();
+      const enabled = live.enabled !== false;
+
+      logger.info('HarborForge Monitor plugin config resolved', {
+        enabled,
+        hasApiKey: Boolean(live.apiKey),
+        backendUrl: live.backendUrl ?? null,
+        identifier: live.identifier ?? null,
+      });
+
+      if (!enabled) {
+        logger.info('HarborForge Monitor plugin disabled');
+        return;
      }
-    }, 5000);

-    sidecar.on('exit', () => {
-      clearTimeout(timeout);
-    });
-  }
+      if (sidecar) {
+        logger.debug('Sidecar already running');
+        return;
+      }

-  // Hook into Gateway lifecycle
-  api.on('gateway:start', () => {
-    logger.info('Gateway starting, starting telemetry server...');
-    startSidecar();
-  });
+      if (!live.apiKey) {
+        logger.warn('Missing config: apiKey');
+        logger.warn('API authentication will fail. Generate apiKey from HarborForge Monitor admin.');
+      }

-  api.on('gateway:stop', () => {
-    logger.info('Gateway stopping, stopping telemetry server...');
-    stopSidecar();
-  });
+      if (!existsSync(serverPath)) {
+        logger.error('Telemetry server not found:', serverPath);
+        return;
+      }

-  // Handle process signals
-  process.on('SIGTERM', stopSidecar);
-  process.on('SIGINT', stopSidecar);
+      logger.info('Starting HarborForge Monitor telemetry server...');

-  // Start immediately if Gateway is already running
-  if (api.isRunning?.()) {
-    startSidecar();
-  } else {
-    setTimeout(() => startSidecar(), 1000);
-  }
-
-  // Register status tool
-  api.registerTool(() => ({
-    name: 'harborforge_monitor_status',
-    description: 'Get HarborForge Monitor plugin status',
-    parameters: {
-      type: 'object',
-      properties: {}
-    },
-    async execute() {
-      return {
-        enabled: true,
-        sidecarRunning: sidecar !== null && sidecar.exitCode === null,
-        pid: sidecar?.pid || null,
-        config: {
-          backendUrl: config.backendUrl,
-          identifier: config.identifier || 'auto-detected',
-          reportIntervalSec: config.reportIntervalSec
-        }
+      const env = {
+        ...process.env,
+        HF_MONITOR_BACKEND_URL: live.backendUrl || 'https://monitor.hangman-lab.top',
+        HF_MONITOR_IDENTIFIER: live.identifier || '',
+        HF_MONITOR_API_KEY: live.apiKey || '',
+        HF_MONITOR_REPORT_INTERVAL: String(live.reportIntervalSec || 30),
+        HF_MONITOR_HTTP_FALLBACK_INTERVAL: String(live.httpFallbackIntervalSec || 60),
+        HF_MONITOR_LOG_LEVEL: live.logLevel || 'info',
+        OPENCLAW_PATH: process.env.OPENCLAW_PATH || join(process.env.HOME || '/root', '.openclaw'),
+        HF_MONITOR_PLUGIN_VERSION: api.version || 'unknown',
      };
-    }
-  }));

-  logger.info('HarborForge Monitor plugin registered');
-}
+      sidecar = spawn('node', [serverPath], {
+        env,
+        detached: false,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+
+      sidecar.stdout?.on('data', (data: Buffer) => {
+        logger.info('[telemetry]', data.toString().trim());
+      });
+
+      sidecar.stderr?.on('data', (data: Buffer) => {
+        logger.error('[telemetry]', data.toString().trim());
+      });
+
+      sidecar.on('exit', (code, signal) => {
+        logger.info(`Telemetry server exited (code: ${code}, signal: ${signal})`);
+        sidecar = null;
+      });
+
+      sidecar.on('error', (err: Error) => {
+        logger.error('Failed to start telemetry server:', err.message);
+        sidecar = null;
+      });
+
+      logger.info('Telemetry server started with PID:', sidecar.pid);
+    }
+
+    function stopSidecar() {
+      if (!sidecar) {
+        logger.debug('Telemetry server not running');
+        return;
+      }
+
+      logger.info('Stopping HarborForge Monitor telemetry server...');
+      sidecar.kill('SIGTERM');
+
+      const timeout = setTimeout(() => {
+        if (sidecar && !sidecar.killed) {
+          logger.warn('Telemetry server did not exit gracefully, forcing kill');
+          sidecar.kill('SIGKILL');
+        }
+      }, 5000);
+
+      sidecar.on('exit', () => {
+        clearTimeout(timeout);
+      });
+    }
+
+    api.on('gateway_start', () => {
+      logger.info('gateway_start received, starting telemetry server...');
+      startSidecar();
+    });
+
+    api.on('gateway_stop', () => {
+      logger.info('gateway_stop received, stopping telemetry server...');
+      stopSidecar();
+    });
+
+    process.on('SIGTERM', stopSidecar);
+    process.on('SIGINT', stopSidecar);
+
+    api.registerTool(() => ({
+      name: 'harborforge_monitor_status',
+      description: 'Get HarborForge Monitor plugin status',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        const live = resolveConfig();
+        return {
+          enabled: live.enabled !== false,
+          sidecarRunning: sidecar !== null && sidecar.exitCode === null,
+          pid: sidecar?.pid || null,
+          config: {
+            backendUrl: live.backendUrl,
+            identifier: live.identifier || 'auto-detected',
+            reportIntervalSec: live.reportIntervalSec,
+            hasApiKey: Boolean(live.apiKey),
+          },
+        };
+      },
+    }));
+
+    logger.info('HarborForge Monitor plugin registered');
+  },
+};
--- a/plugin/openclaw.plugin.json
+++ b/plugin/openclaw.plugin.json
@@ -22,9 +22,9 @@
        "type": "string",
        "description": "Server identifier (auto-detected from hostname if not set)"
      },
-      "challengeUuid": { 
+      "apiKey": { 
        "type": "string",
-        "description": "Registration challenge UUID from Monitor"
+        "description": "API Key from HarborForge Monitor admin panel (optional but required for authentication)"
      },
      "reportIntervalSec": { 
        "type": "number", 
@@ -42,7 +42,6 @@
        "default": "info",
        "description": "Logging level"
      }
-    },
-    "required": ["challengeUuid"]
+    }
  }
 }
--- a/plugin/package-lock.json
+++ b/plugin/package-lock.json
@@ -0,0 +1,48 @@
+{
+  "name": "harborforge-monitor-plugin",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "harborforge-monitor-plugin",
+      "version": "0.1.0",
+      "license": "MIT",
+      "devDependencies": {
+        "@types/node": "^20.0.0",
+        "typescript": "^5.0.0"
+      }
+    },
+    "node_modules/@types/node": {
+      "version": "20.19.37",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",
+      "integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~6.21.0"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    },
+    "node_modules/undici-types": {
+      "version": "6.21.0",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+      "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+      "dev": true,
+      "license": "MIT"
+    }
+  }
+}
--- a/plugin/tsconfig.json
+++ b/plugin/tsconfig.json
@@ -1,8 +1,8 @@
 {
  "compilerOptions": {
    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
+    "module": "CommonJS",
+    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true,
@@ -12,6 +12,6 @@
    "declarationMap": true,
    "sourceMap": true
  },
-  "include": ["*.ts"],
+  "include": ["**/*.ts"],
  "exclude": ["node_modules"]
 }
--- a/scripts/install.mjs
+++ b/scripts/install.mjs
@@ -240,8 +240,8 @@ async function configure() {
    }
    logOk(`plugins.allow includes ${PLUGIN_NAME}`);
    
-    // Note: challengeUuid must be configured manually by user
-    logOk('Plugin configured (remember to set challengeUuid in ~/.openclaw/openclaw.json)');
+    // Note: apiKey must be configured manually by user
+    logOk('Plugin configured (remember to set apiKey in plugins.entries.harborforge-monitor.config)');
    
  } catch (err) {
    logWarn(`Config failed: ${err.message}`);
@@ -262,13 +262,18 @@ function summary() {
  
  console.log('');
  log('Next steps:', 'blue');
-  log(' 1. Register server in HarborForge Monitor to get challengeUuid', 'cyan');
-  log(' 2. Edit ~/.openclaw/openclaw.json:', 'cyan');
+  log(' 1. Register server in HarborForge Monitor to get apiKey', 'cyan');
+  log(' 2. Edit ~/.openclaw/openclaw.json under plugins.entries.harborforge-monitor.config:', 'cyan');
  log('    {', 'cyan');
  log('      "plugins": {', 'cyan');
-  log('        "harborforge-monitor": {', 'cyan');
-  log('          "enabled": true,', 'cyan');
-  log('          "challengeUuid": "your-challenge-uuid"', 'cyan');
+  log('        "entries": {', 'cyan');
+  log('          "harborforge-monitor": {', 'cyan');
+  log('            "enabled": true,', 'cyan');
+  log('            "config": {', 'cyan');
+  log('              "enabled": true,', 'cyan');
+  log('              "apiKey": "your-api-key"', 'cyan');
+  log('            }', 'cyan');
+  log('          }', 'cyan');
  log('        }', 'cyan');
  log('      }', 'cyan');
  log('    }', 'cyan');
--- a/server/telemetry.mjs
+++ b/server/telemetry.mjs
@@ -4,24 +4,27 @@
 * Runs as separate process from Gateway.
 * Collects system metrics and OpenClaw status, sends to Monitor.
 */
-import { readFile, access } from 'fs/promises';
+import { readFile, access, readdir } from 'fs/promises';
 import { constants } from 'fs';
 import { exec } from 'child_process';
 import { promisify } from 'util';
-import { platform, hostname, freemem, totalmem, uptime } from 'os';
+import { platform, hostname, freemem, totalmem, uptime, loadavg } from 'os';

 const execAsync = promisify(exec);

 // Config from environment (set by plugin)
+const openclawPath = process.env.OPENCLAW_PATH || `${process.env.HOME}/.openclaw`;
 const CONFIG = {
  backendUrl: process.env.HF_MONITOR_BACKEND_URL || 'https://monitor.hangman-lab.top',
  identifier: process.env.HF_MONITOR_IDENTIFIER || hostname(),
-  challengeUuid: process.env.HF_MONITOR_CHALLENGE_UUID,
+  apiKey: process.env.HF_MONITOR_API_KEY,
  reportIntervalSec: parseInt(process.env.HF_MONITOR_REPORT_INTERVAL || '30', 10),
  httpFallbackIntervalSec: parseInt(process.env.HF_MONITOR_HTTP_FALLBACK_INTERVAL || '60', 10),
  logLevel: process.env.HF_MONITOR_LOG_LEVEL || 'info',
-  openclawPath: process.env.OPENCLAW_PATH || `${process.env.HOME}/.openclaw`,
-  openclawVersion: process.env.OPENCLAW_VERSION || 'unknown',
+  openclawPath,
+  pluginVersion: process.env.HF_MONITOR_PLUGIN_VERSION || 'unknown',
+  cachePath: process.env.HF_MONITOR_CACHE_PATH || `${openclawPath}/telemetry_cache.json`,
+  maxCacheSize: parseInt(process.env.HF_MONITOR_MAX_CACHE_SIZE || '100', 10),
 };

 // Logging
@@ -37,6 +40,7 @@ let wsConnection = null;
 let lastSuccessfulSend = null;
 let consecutiveFailures = 0;
 let isShuttingDown = false;
+let cachedOpenclawVersion = null;

 /**
 * Collect system metrics
@@ -48,7 +52,7 @@ async function collectSystemMetrics() {
    const memFree = freemem();
    const memUsed = memTotal - memFree;
    const diskInfo = await getDiskUsage();
-    const loadAvg = platform() !== 'win32' ? require('os').loadavg() : [0, 0, 0];
+    const loadAvg = platform() !== 'win32' ? loadavg() : [0, 0, 0];
    
    return {
      cpu_pct: cpuUsage,
@@ -59,8 +63,12 @@ async function collectSystemMetrics() {
      disk_used_gb: Math.round(diskInfo.usedGB * 10) / 10,
      disk_total_gb: Math.round(diskInfo.totalGB * 10) / 10,
      swap_pct: diskInfo.swapUsedPct || 0,
-      uptime_sec: Math.floor(uptime()),
-      load_avg_1m: Math.round(loadAvg[0] * 100) / 100,
+      uptime_seconds: Math.floor(uptime()),
+      load_avg: [
+        Math.round(loadAvg[0] * 100) / 100,
+        Math.round(loadAvg[1] * 100) / 100,
+        Math.round(loadAvg[2] * 100) / 100,
+      ],
      platform: platform(),
      hostname: hostname(),
    };
@@ -129,14 +137,33 @@ function parseSizeToGB(size) {
  return num;
 }

+async function resolveOpenclawVersion() {
+  if (cachedOpenclawVersion) return cachedOpenclawVersion;
+
+  try {
+    const { stdout } = await execAsync('openclaw --version');
+    const version = stdout.trim();
+    cachedOpenclawVersion = version || 'unknown';
+    return cachedOpenclawVersion;
+  } catch (err) {
+    log.debug('Failed to resolve OpenClaw version:', err.message);
+    cachedOpenclawVersion = 'unknown';
+    return cachedOpenclawVersion;
+  }
+}
+
 /**
 * Collect OpenClaw status
 */
 async function collectOpenclawStatus() {
  try {
-    const agents = await getOpenclawAgents();
+    const [agents, openclawVersion] = await Promise.all([
+      getOpenclawAgents(),
+      resolveOpenclawVersion(),
+    ]);
    return {
-      version: CONFIG.openclawVersion,
+      openclawVersion,
+      pluginVersion: CONFIG.pluginVersion,
      agent_count: agents.length,
      agents: agents.map(a => ({
        id: a.id,
@@ -146,23 +173,93 @@ async function collectOpenclawStatus() {
    };
  } catch (err) {
    log.debug('Failed to collect OpenClaw status:', err.message);
-    return { version: CONFIG.openclawVersion, agent_count: 0, agents: [] };
+    return {
+      openclawVersion: await resolveOpenclawVersion(),
+      pluginVersion: CONFIG.pluginVersion,
+      agent_count: 0,
+      agents: [],
+    };
  }
 }

 /**
 * Get list of OpenClaw agents from local state
 */
+function extractJsonPrefix(text) {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  const startsWith = trimmed[0];
+  if (startsWith !== '[' && startsWith !== '{') return null;
+
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = 0; i < trimmed.length; i += 1) {
+    const ch = trimmed[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === '\\') {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === '[' || ch === '{') depth += 1;
+    if (ch === ']' || ch === '}') depth -= 1;
+    if (depth === 0) {
+      return trimmed.slice(0, i + 1);
+    }
+  }
+  return null;
+}
+
 async function getOpenclawAgents() {
  try {
+    try {
+      const { stdout } = await execAsync('openclaw agents list --json 2>/dev/null');
+      const jsonPrefix = extractJsonPrefix(stdout);
+      if (jsonPrefix) {
+        const agents = JSON.parse(jsonPrefix);
+        if (Array.isArray(agents)) {
+          return agents.map((agent) => ({
+            id: agent.id,
+            name: agent.name || agent.id,
+            status: agent.isDefault ? 'default' : 'configured',
+          }));
+        }
+      }
+    } catch (err) {
+      log.debug('Failed to get agents from `openclaw agents list --json`:', err.message);
+    }
+
    const agentConfigPath = `${CONFIG.openclawPath}/agents.json`;
    try {
      await access(agentConfigPath, constants.R_OK);
      const data = JSON.parse(await readFile(agentConfigPath, 'utf8'));
-      return data.agents || [];
+      if (Array.isArray(data.agents) && data.agents.length > 0) {
+        return data.agents;
+      }
    } catch {
-      return [];
+      // fall through to directory-based discovery
    }
+
+    const agentsDir = `${CONFIG.openclawPath}/agents`;
+    await access(agentsDir, constants.R_OK);
+    const entries = await readdir(agentsDir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => entry.name !== 'main')
+      .map((entry) => ({
+        id: entry.name,
+        name: entry.name,
+        status: 'configured',
+      }));
  } catch {
    return [];
  }
@@ -177,12 +274,11 @@ async function buildPayload() {
  
  return {
    identifier: CONFIG.identifier,
-    challenge_uuid: CONFIG.challengeUuid,
    timestamp: new Date().toISOString(),
    ...system,
-    openclaw_version: openclaw.version,
-    openclaw_agents: openclaw.agents,
-    openclaw_agent_count: openclaw.agent_count,
+    openclaw_version: openclaw.openclawVersion,
+    plugin_version: openclaw.pluginVersion,
+    agents: openclaw.agents,
  };
 }

@@ -194,13 +290,18 @@ async function sendHttpHeartbeat() {
    const payload = await buildPayload();
    log.debug('Sending HTTP heartbeat...');
    
-    const response = await fetch(`${CONFIG.backendUrl}/monitor/server/heartbeat`, {
+    const headers = {
+      'Content-Type': 'application/json',
+      'X-Server-Identifier': CONFIG.identifier,
+    };
+    
+    if (CONFIG.apiKey) {
+      headers['X-API-Key'] = CONFIG.apiKey;
+    }
+    
+    const response = await fetch(`${CONFIG.backendUrl}/monitor/server/heartbeat-v2`, {
      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-Server-Identifier': CONFIG.identifier,
-        'X-Challenge-UUID': CONFIG.challengeUuid,
-      },
+      headers,
      body: JSON.stringify(payload),
    });
    
@@ -268,11 +369,12 @@ log.info('Config:', {
  identifier: CONFIG.identifier,
  backendUrl: CONFIG.backendUrl,
  reportIntervalSec: CONFIG.reportIntervalSec,
+  hasApiKey: !!CONFIG.apiKey,
+  pluginVersion: CONFIG.pluginVersion,
 });

-if (!CONFIG.challengeUuid) {
-  log.error('Missing HF_MONITOR_CHALLENGE_UUID environment variable');
-  process.exit(1);
+if (!CONFIG.apiKey) {
+  log.warn('Missing HF_MONITOR_API_KEY environment variable - API authentication will fail');
 }

 reportingLoop();
				`@@ -0,0 +1 @@`
				{"version":3,"file":"live-config.d.ts","sourceRoot":"","sources":["live-config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,wBAAwB;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;CAChD;AAED,UAAU,qBAAqB;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,qBAAqB,EAC1B,QAAQ,EAAE,wBAAwB,GACjC,wBAAwB,CAqB1B"}
				`@@ -0,0 +1 @@`
				{"version":3,"file":"live-config.js","sourceRoot":"","sources":["live-config.ts"],"names":[],"mappings":";;AAcA,kDAwBC;AAxBD,SAAgB,mBAAmB,CACjC,GAA0B,EAC1B,QAAkC;IAElC,MAAM,IAAI,GAAI,GAAG,CAAC,MAAkC,IAAI,EAAE,CAAC;IAC3D,MAAM,OAAO,GAAI,IAAI,CAAC,OAAmC,IAAI,EAAE,CAAC;IAChE,MAAM,OAAO,GAAI,OAAO,CAAC,OAAmC,IAAI,EAAE,CAAC;IACnE,MAAM,KAAK,GAAI,OAAO,CAAC,qBAAqB,CAA6B,IAAI,EAAE,CAAC;IAChF,MAAM,GAAG,GAAI,KAAK,CAAC,MAAkC,IAAI,EAAE,CAAC;IAE5D,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjE,OAAO;YACL,GAAG,QAAQ;YACX,GAAG,GAAG;YACN,OAAO,EACL,OAAO,GAAG,CAAC,OAAO,KAAK,SAAS;gBAC9B,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,OAAO,KAAK,CAAC,OAAO,KAAK,SAAS;oBAClC,CAAC,CAAC,KAAK,CAAC,OAAO;oBACf,CAAC,CAAC,QAAQ,CAAC,OAAO;SACG,CAAC;IAChC,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}