feat: add POST /openclaw endpoint and enrich heartbeats with OpenClaw metadata

- Bridge server now accepts POST /openclaw from OpenClaw plugin - OpenClawMeta struct stores version, plugin_version, and agents - Heartbeat sendOnce() enriches payload with plugin metadata when available - Telemetry Payload adds optional openclaw_version field - README updated to document /openclaw endpoint and metadata enrichment - All communication remains optional — Monitor functions without plugin data
Add local monitor bridge service
2026-03-22 01:37:15 +00:00 · 2026-03-21 16:07:00 +00:00 · 2026-03-21 15:25:02 +00:00
8 changed files with 318 additions and 21 deletions
--- a/3
+++ b/3
@@ -15,6 +15,7 @@ ENV HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \
    HF_MONITER_API_KEY= \
    HF_MONITER_REPORT_INTERVAL=30 \
    HF_MONITER_LOG_LEVEL=info \
-    HF_MONITER_ROOTFS=/host
+    HF_MONITER_ROOTFS=/host \
+    MONITOR_PORT=0

 ENTRYPOINT ["/usr/local/bin/harborforge-monitor"]
--- a/README.md
+++ b/README.md
@@ -29,7 +29,9 @@ HarborForge.Monitor/
 ├── cmd/harborforge-monitor/      # 程序入口
 ├── internal/config/              # 配置加载
 ├── internal/telemetry/           # 指标采集与上报
+├── internal/bridge/              # MONITOR_PORT 本地桥接服务
 ├── Dockerfile                    # 容器化运行
+├── docker-compose.yml            # Docker Compose 配置
 ├── config.example.json
 └── README.md
 ```
@@ -46,7 +48,8 @@ HarborForge.Monitor/
  "identifier": "vps-nginx-01",
  "apiKey": "your-api-key",
  "reportIntervalSec": 30,
-  "logLevel": "info"
+  "logLevel": "info",
+  "monitorPort": 9100
 }
 ```

@@ -61,6 +64,35 @@ HarborForge.Monitor/

 同时也兼容旧的/正确拼写的 `HF_MONITOR_*` 变量名。

+### MONITOR_PORT — 插件桥接端口
+
+当 `MONITOR_PORT` (或 `monitorPort`) 设置为大于 0 的值时，Monitor 会在 `127.0.0.1:<MONITOR_PORT>` 上启动一个本地 HTTP 服务，供 HarborForge OpenClaw 插件查询遥测数据。
+
+支持的端点：
+
+| 端点 | 说明 |
+|------|------|
+| `GET /health` | 健康检查，返回 Monitor 版本和标识符 |
+| `GET /telemetry` | 返回最新的遥测数据快照 |
+| `POST /openclaw` | 接收 OpenClaw 插件推送的元数据（版本、代理等） |
+
+### OpenClaw 元数据 enrichment
+
+当 OpenClaw 插件通过 `POST /openclaw` 推送元数据后，Monitor 会在后续的心跳上报中自动将这些信息附加到遥测数据中：
+
+- `openclaw_version` — OpenClaw 运行时版本
+- `plugin_version` — 插件版本
+- `agents` — 代理列表
+
+如果插件从未推送过元数据，这些字段会被省略，心跳上报完全不受影响。
+
+**重要**：桥接端口是可选的。如果 `MONITOR_PORT` 为 0 或未设置，桥接服务不会启动，Monitor 的心跳上报功能完全不受影响。即使桥接服务启动失败，心跳上报也会继续正常工作。
+
+环境变量：
+
+- `MONITOR_PORT` — 首选
+- `HF_MONITOR_PORT` — 备选
+
 ## 本地开发

 ```bash
@@ -77,34 +109,46 @@ go build ./cmd/harborforge-monitor
 docker build -t harborforge-monitor .
 ```

+### 使用 Docker Compose
+
+```bash
+# 设置环境变量
+export HF_IDENTIFIER=my-server
+export HF_API_KEY=your-api-key
+export MONITOR_PORT=9100
+
+# 启动
+docker compose up -d
+```
+
+### 手动 Docker 运行
+
 推荐以**宿主机 rootfs 只读挂载**方式运行，这样容器里采集到的是宿主机信息而不是容器自身：

 ```bash
 docker run -d \
  --name harborforge-monitor \
  --restart unless-stopped \
-  -e HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \
-  -e HF_MONITER_IDENTIFIER=vps-nginx-01 \
-  -e HF_MONITER_API_KEY=your-api-key \
-  -e HF_MONITER_REPORT_INTERVAL=30 \
-  -e HF_MONITER_ROOTFS=/host \
+  --network host \
  -v /:/host:ro \
+  -e HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top \
+  -e HF_MONITER_IDENTIFIER=my-server \
+  -e HF_MONITER_API_KEY=your-api-key \
+  -e HF_MONITER_ROOTFS=/host \
+  -e MONITOR_PORT=9100 \
  harborforge-monitor
 ```

-`Dockerfile` 里已经预置了这些环境变量：
+## systemd

- `HF_MONITER_BACKEND_URL`
- `HF_MONITER_IDENTIFIER`
- `HF_MONITER_API_KEY`
- `HF_MONITER_REPORT_INTERVAL`
- `HF_MONITER_LOG_LEVEL`
- `HF_MONITER_ROOTFS`
+也可以直接用 systemd 运行编译好的二进制：

-## 注意
+```bash
+# 编译
+go build -o /usr/local/bin/harborforge-monitor ./cmd/harborforge-monitor

- Docker 模式下，建议挂载 `-v /:/host:ro` 并设置 `HF_MONITER_ROOTFS=/host`
- 这样 CPU/MEM/LOAD/UPTIME 会通过 host proc/sys 视角采集，磁盘和 nginx 配置也会走宿主机路径
- 当前 Nginx site 列表读取的是 `${ROOTFS}/etc/nginx/sites-enabled`
- 如果机器没有安装 Nginx，会回报 `nginx_installed = false`
- 该客户端不会尝试读取 OpenClaw 信息，`agents` 默认为空，`openclaw_version` 不上报
+# 复制 systemd unit (见 systemd/ 目录)
+cp systemd/harborforge-monitor.service /etc/systemd/system/
+systemctl daemon-reload
+systemctl enable --now harborforge-monitor
+```
--- a/cmd/harborforge-monitor/main.go
+++ b/cmd/harborforge-monitor/main.go
@@ -12,6 +12,7 @@ import (
 	"syscall"
 	"time"

+	"git.hangman-lab.top/zhi/HarborForge.Monitor/internal/bridge"
 	"git.hangman-lab.top/zhi/HarborForge.Monitor/internal/config"
 	"git.hangman-lab.top/zhi/HarborForge.Monitor/internal/telemetry"
 )
@@ -50,11 +51,43 @@ func main() {
 	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
 	defer stop()

+	// Start the bridge server if MONITOR_PORT is configured.
+	// The bridge is independent of heartbeat — if it fails to start,
+	// heartbeat continues normally.
+	var bridgeSrv *bridge.Server
+	if cfg.MonitorPort > 0 {
+		bridgeSrv = bridge.New(cfg, logger)
+		go func() {
+			if err := bridgeSrv.Start(ctx); err != nil {
+				logger.Printf("bridge error (non-fatal): %v", err)
+			}
+		}()
+	}
+
 	sendOnce := func() error {
 		payload, err := telemetry.BuildPayload(ctx, cfg)
 		if err != nil {
 			return err
 		}
+
+		// Update bridge with latest telemetry
+		if bridgeSrv != nil {
+			bridgeSrv.UpdatePayload(payload)
+
+			// Enrich payload with OpenClaw metadata if available
+			if meta := bridgeSrv.GetOpenClawMeta(); meta != nil {
+				if meta.Version != "" {
+					payload.OpenClawVersion = meta.Version
+				}
+				if meta.PluginVersion != "" {
+					payload.PluginVersion = meta.PluginVersion
+				}
+				if len(meta.Agents) > 0 {
+					payload.Agents = meta.Agents
+				}
+			}
+		}
+
 		if printPayload || dryRun {
 			buf, _ := json.MarshalIndent(payload, "", "  ")
 			fmt.Println(string(buf))
--- a/config.example.json
+++ b/config.example.json
@@ -4,5 +4,6 @@
  "apiKey": "replace-with-server-api-key",
  "reportIntervalSec": 30,
  "logLevel": "info",
-  "rootFs": "/host"
+  "rootFs": "/host",
+  "monitorPort": 9100
 }
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -0,0 +1,22 @@
+version: "3.8"
+
+services:
+  harborforge-monitor:
+    build: .
+    container_name: harborforge-monitor
+    restart: unless-stopped
+    environment:
+      - HF_MONITER_BACKEND_URL=https://monitor.hangman-lab.top
+      - HF_MONITER_IDENTIFIER=${HF_IDENTIFIER:-}
+      - HF_MONITER_API_KEY=${HF_API_KEY:-}
+      - HF_MONITER_REPORT_INTERVAL=${HF_REPORT_INTERVAL:-30}
+      - HF_MONITER_LOG_LEVEL=${HF_LOG_LEVEL:-info}
+      - HF_MONITER_ROOTFS=/host
+      - MONITOR_PORT=${MONITOR_PORT:-0}
+    volumes:
+      - /:/host:ro
+    ports:
+      # Expose MONITOR_PORT on 127.0.0.1 only for plugin communication.
+      # Only active when MONITOR_PORT > 0.
+      - "127.0.0.1:${MONITOR_PORT:-9100}:${MONITOR_PORT:-9100}"
+    network_mode: host
--- a/internal/bridge/bridge.go
+++ b/internal/bridge/bridge.go
@@ -0,0 +1,187 @@
+// Package bridge provides a local HTTP server on MONITOR_PORT for
+// communication between the HarborForge OpenClaw plugin and Monitor.
+//
+// The bridge serves two purposes:
+//  1. Expose hardware telemetry to the plugin via GET /telemetry
+//  2. Receive OpenClaw metadata from the plugin via POST /openclaw
+//
+// The bridge is optional: if monitorPort is 0 or not set, the bridge
+// is not started and Monitor operates normally.
+package bridge
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"net/http"
+	"sync"
+	"time"
+
+	"git.hangman-lab.top/zhi/HarborForge.Monitor/internal/config"
+	"git.hangman-lab.top/zhi/HarborForge.Monitor/internal/telemetry"
+)
+
+// OpenClawMeta holds metadata received from the OpenClaw plugin.
+// This data is optional enrichment for heartbeat uploads.
+type OpenClawMeta struct {
+	Version       string `json:"version"`
+	PluginVersion string `json:"plugin_version"`
+	Agents        []any  `json:"agents,omitempty"`
+}
+
+// Server is the local bridge HTTP server.
+type Server struct {
+	cfg    config.Config
+	logger *log.Logger
+	srv    *http.Server
+
+	mu          sync.RWMutex
+	lastPayload *telemetry.Payload
+	lastUpdated time.Time
+
+	openclawMeta    *OpenClawMeta
+	openclawUpdated time.Time
+}
+
+// New creates a bridge server. It does not start listening.
+func New(cfg config.Config, logger *log.Logger) *Server {
+	return &Server{
+		cfg:    cfg,
+		logger: logger,
+	}
+}
+
+// UpdatePayload stores the latest telemetry payload so the bridge can
+// serve it to plugin queries without re-collecting.
+func (s *Server) UpdatePayload(p telemetry.Payload) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.lastPayload = &p
+	s.lastUpdated = time.Now()
+}
+
+// bridgeResponse is the JSON structure served to the plugin.
+type bridgeResponse struct {
+	Status      string             `json:"status"`
+	MonitorVer  string             `json:"monitor_version"`
+	Identifier  string             `json:"identifier"`
+	Telemetry   *telemetry.Payload `json:"telemetry,omitempty"`
+	LastUpdated *time.Time         `json:"last_updated,omitempty"`
+}
+
+// GetOpenClawMeta returns the latest OpenClaw metadata received from
+// the plugin, or nil if no metadata has been received.
+func (s *Server) GetOpenClawMeta() *OpenClawMeta {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.openclawMeta
+}
+
+func (s *Server) handler() http.Handler {
+	mux := http.NewServeMux()
+
+	// Health / discovery endpoint
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{
+			"status":          "ok",
+			"monitor_version": telemetry.Version,
+			"identifier":      s.cfg.Identifier,
+		})
+	})
+
+	// Telemetry endpoint — returns the latest cached payload
+	mux.HandleFunc("/telemetry", func(w http.ResponseWriter, r *http.Request) {
+		s.mu.RLock()
+		payload := s.lastPayload
+		updated := s.lastUpdated
+		s.mu.RUnlock()
+
+		resp := bridgeResponse{
+			Status:     "ok",
+			MonitorVer: telemetry.Version,
+			Identifier: s.cfg.Identifier,
+		}
+		if payload != nil {
+			resp.Telemetry = payload
+			resp.LastUpdated = &updated
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	// OpenClaw metadata endpoint — plugin POSTs its metadata here
+	mux.HandleFunc("/openclaw", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+
+		body, err := io.ReadAll(io.LimitReader(r.Body, 64*1024))
+		if err != nil {
+			http.Error(w, "read error", http.StatusBadRequest)
+			return
+		}
+		defer r.Body.Close()
+
+		var meta OpenClawMeta
+		if err := json.Unmarshal(body, &meta); err != nil {
+			http.Error(w, "invalid json", http.StatusBadRequest)
+			return
+		}
+
+		s.mu.Lock()
+		s.openclawMeta = &meta
+		s.openclawUpdated = time.Now()
+		s.mu.Unlock()
+
+		s.logger.Printf("received OpenClaw metadata: version=%s plugin=%s agents=%d",
+			meta.Version, meta.PluginVersion, len(meta.Agents))
+
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(map[string]string{
+			"status": "ok",
+		})
+	})
+
+	return mux
+}
+
+// Start begins listening on 127.0.0.1:<monitorPort>. It blocks until
+// the context is cancelled or an error occurs.
+func (s *Server) Start(ctx context.Context) error {
+	if s.cfg.MonitorPort <= 0 {
+		return nil // bridge disabled
+	}
+
+	addr := fmt.Sprintf("127.0.0.1:%d", s.cfg.MonitorPort)
+	listener, err := net.Listen("tcp", addr)
+	if err != nil {
+		return fmt.Errorf("bridge listen on %s: %w", addr, err)
+	}
+
+	s.srv = &http.Server{
+		Handler:      s.handler(),
+		ReadTimeout:  5 * time.Second,
+		WriteTimeout: 5 * time.Second,
+		IdleTimeout:  30 * time.Second,
+	}
+
+	s.logger.Printf("bridge listening on %s", addr)
+
+	go func() {
+		<-ctx.Done()
+		shutCtx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+		defer cancel()
+		s.srv.Shutdown(shutCtx)
+	}()
+
+	if err := s.srv.Serve(listener); err != nil && err != http.ErrServerClosed {
+		return fmt.Errorf("bridge serve: %w", err)
+	}
+	return nil
+}
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -14,6 +14,7 @@ type Config struct {
 	ReportIntervalSec int    `json:"reportIntervalSec"`
 	LogLevel          string `json:"logLevel"`
 	RootFS            string `json:"rootFs"`
+	MonitorPort       int    `json:"monitorPort"`
 }

 func Load(path string) (Config, error) {
@@ -43,6 +44,7 @@ func Load(path string) (Config, error) {
 	cfg.ReportIntervalSec = getenvIntAny([]string{"HF_MONITER_REPORT_INTERVAL", "HF_MONITOR_REPORT_INTERVAL"}, cfg.ReportIntervalSec)
 	cfg.LogLevel = getenvAny([]string{"HF_MONITER_LOG_LEVEL", "HF_MONITOR_LOG_LEVEL"}, cfg.LogLevel)
 	cfg.RootFS = getenvAny([]string{"HF_MONITER_ROOTFS", "HF_MONITOR_ROOTFS"}, cfg.RootFS)
+	cfg.MonitorPort = getenvIntAny([]string{"MONITOR_PORT", "HF_MONITOR_PORT"}, cfg.MonitorPort)

 	if cfg.BackendURL == "" {
 		return cfg, fmt.Errorf("backendUrl is required")
@@ -88,6 +90,9 @@ func merge(dst *Config, src Config) {
 	if src.RootFS != "" {
 		dst.RootFS = src.RootFS
 	}
+	if src.MonitorPort > 0 {
+		dst.MonitorPort = src.MonitorPort
+	}
 }

 func getenvAny(keys []string, fallback string) string {
--- a/internal/telemetry/telemetry.go
+++ b/internal/telemetry/telemetry.go
@@ -35,6 +35,10 @@ type Payload struct {
 	SwapPct        float64   `json:"swap_pct,omitempty"`
 	LoadAvg        []float64 `json:"load_avg,omitempty"`
 	UptimeSeconds  uint64    `json:"uptime_seconds,omitempty"`
+
+	// Optional OpenClaw metadata, enriched from plugin bridge.
+	// These fields are omitted if no plugin data is available.
+	OpenClawVersion string `json:"openclaw_version,omitempty"`
 }

 func BuildPayload(ctx context.Context, cfg config.Config) (Payload, error) {