fix: correct telemetry identifier and visibility when containerized

Three related fixes for running Monitor inside a container with
/:/host:ro bind-mounted and network_mode: host.

* config: when HF_MONITER_ROOTFS is set, read the default identifier
  from <rootFS>/etc/hostname instead of os.Hostname(). Under
  network_mode: host the UTS namespace is not shared, so os.Hostname()
  returns a random docker-assigned string that changes across
  recreations, causing the backend to treat each restart as a new
  server.

* telemetry: log gopsutil errors from BuildPayload instead of silently
  swallowing them. Previously a missing /host mount would send a
  payload full of zeroed fields with no indication of failure.

* docker-compose: drop the 'ports:' block. It is silently ignored
  under network_mode: host (the bridge server binds directly on the
  host's 127.0.0.1:MONITOR_PORT).

README.md

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

cmd/harborforge-monitor/main.go

@@ -24,12 +24,26 @@ func main() {
 		printPayload bool
 		dryRun       bool
 		showVersion  bool
+		backendURL   string
+		identifier   string
+		apiKey       string
+		reportInt    int
+		logLevel     string
+		rootFS       string
+		monitorPort  int
 	)
 	flag.StringVar(&configPath, "config", "/etc/harborforge-monitor/config.json", "Path to config file")
 	flag.BoolVar(&runOnce, "once", false, "Collect and send telemetry once, then exit")
 	flag.BoolVar(&printPayload, "print-payload", false, "Print payload JSON before sending")
 	flag.BoolVar(&dryRun, "dry-run", false, "Collect telemetry but do not send it")
 	flag.BoolVar(&showVersion, "version", false, "Print version and exit")
+	flag.StringVar(&backendURL, "backend-url", "", "Override backend URL")
+	flag.StringVar(&identifier, "identifier", "", "Override identifier")
+	flag.StringVar(&apiKey, "api-key", "", "Override API key")
+	flag.IntVar(&reportInt, "report-interval", 0, "Override report interval in seconds")
+	flag.StringVar(&logLevel, "log-level", "", "Override log level")
+	flag.StringVar(&rootFS, "rootfs", "", "Override root filesystem path")
+	flag.IntVar(&monitorPort, "monitor-port", 0, "Override monitor bridge port")
 	flag.Parse()
 
 	if showVersion {
@@ -37,7 +51,15 @@ func main() {
 		return
 	}
 
-	cfg, err := config.Load(configPath)
+	cfg, err := config.LoadWithOverrides(configPath, config.Overrides{
+		BackendURL:        backendURL,
+		Identifier:        identifier,
+		APIKey:            apiKey,
+		ReportIntervalSec: reportInt,
+		LogLevel:          logLevel,
+		RootFS:            rootFS,
+		MonitorPort:       monitorPort,
+	})
 	if err != nil {
 		log.Fatalf("load config: %v", err)
 	}
@@ -73,6 +95,19 @@ func main() {
 		// 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 {

docker-compose.yml

@@ -15,8 +15,8 @@ services:
       - MONITOR_PORT=${MONITOR_PORT:-0}
     volumes:
       - /:/host:ro
-    ports:
+    # network_mode: host shares the host network namespace, so the bridge
-      # Expose MONITOR_PORT on 127.0.0.1 only for plugin communication.
+    # server (if MONITOR_PORT > 0) listens directly on the host's
-      # Only active when MONITOR_PORT > 0.
+    # 127.0.0.1:<MONITOR_PORT>. `ports:` is ignored under network_mode:
-      - "127.0.0.1:${MONITOR_PORT:-9100}:${MONITOR_PORT:-9100}"
+    # host, so it is intentionally omitted.
     network_mode: host

internal/bridge/bridge.go

@@ -1,15 +1,19 @@
 // Package bridge provides a local HTTP server on MONITOR_PORT for
 // communication between the HarborForge OpenClaw plugin and Monitor.
 //
-// The plugin queries this endpoint to enrich its telemetry with
+// The bridge serves two purposes:
-// host/hardware data. The bridge is optional: if monitorPort is 0
+//  1. Expose hardware telemetry to the plugin via GET /telemetry
-// or not set, the bridge is not started and Monitor operates normally.
+//  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"
@@ -20,6 +24,14 @@ import (
 	"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
@@ -29,6 +41,9 @@ type Server struct {
 	mu          sync.RWMutex
 	lastPayload *telemetry.Payload
 	lastUpdated time.Time
+
+	openclawMeta    *OpenClawMeta
+	openclawUpdated time.Time
 }
 
 // New creates a bridge server. It does not start listening.
@@ -57,6 +72,14 @@ type bridgeResponse struct {
 	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()
 
@@ -91,6 +114,40 @@ func (s *Server) handler() http.Handler {
 		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
 }
 

internal/config/config.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"path/filepath"
+	"strings"
 )
 
 type Config struct {
@@ -17,10 +18,34 @@ type Config struct {
 	MonitorPort       int    `json:"monitorPort"`
 }
 
+type Overrides struct {
+	BackendURL        string
+	Identifier        string
+	APIKey            string
+	ReportIntervalSec int
+	LogLevel          string
+	RootFS            string
+	MonitorPort       int
+}
+
 func Load(path string) (Config, error) {
+	return LoadWithOverrides(path, Overrides{})
+}
+
+func LoadWithOverrides(path string, overrides Overrides) (Config, error) {
+	// If running inside a container with the host FS bind-mounted, prefer
+	// the host's /etc/hostname for the default identifier. The container's
+	// own os.Hostname() is a docker-assigned random string under
+	// network_mode: host (UTS namespace is not shared).
+	rootFSEarly := getenvAny([]string{"HF_MONITER_ROOTFS", "HF_MONITOR_ROOTFS"}, "")
+	defaultIdentifier := hostHostname(rootFSEarly)
+	if defaultIdentifier == "" {
+		defaultIdentifier = hostnameOr("unknown-host")
+	}
+
 	cfg := Config{
 		BackendURL:        getenvAny([]string{"HF_MONITER_BACKEND_URL", "HF_MONITOR_BACKEND_URL"}, "https://monitor.hangman-lab.top"),
-		Identifier:        getenvAny([]string{"HF_MONITER_IDENTIFIER", "HF_MONITOR_IDENTIFIER"}, hostnameOr("unknown-host")),
+		Identifier:        getenvAny([]string{"HF_MONITER_IDENTIFIER", "HF_MONITOR_IDENTIFIER"}, defaultIdentifier),
 		APIKey:            getenvAny([]string{"HF_MONITER_API_KEY", "HF_MONITOR_API_KEY"}, ""),
 		ReportIntervalSec: getenvIntAny([]string{"HF_MONITER_REPORT_INTERVAL", "HF_MONITOR_REPORT_INTERVAL"}, 30),
 		LogLevel:          getenvAny([]string{"HF_MONITER_LOG_LEVEL", "HF_MONITOR_LOG_LEVEL"}, "info"),
@@ -46,6 +71,28 @@ func Load(path string) (Config, error) {
 	cfg.RootFS = getenvAny([]string{"HF_MONITER_ROOTFS", "HF_MONITOR_ROOTFS"}, cfg.RootFS)
 	cfg.MonitorPort = getenvIntAny([]string{"MONITOR_PORT", "HF_MONITOR_PORT"}, cfg.MonitorPort)
 
+	if overrides.BackendURL != "" {
+		cfg.BackendURL = overrides.BackendURL
+	}
+	if overrides.Identifier != "" {
+		cfg.Identifier = overrides.Identifier
+	}
+	if overrides.APIKey != "" {
+		cfg.APIKey = overrides.APIKey
+	}
+	if overrides.ReportIntervalSec > 0 {
+		cfg.ReportIntervalSec = overrides.ReportIntervalSec
+	}
+	if overrides.LogLevel != "" {
+		cfg.LogLevel = overrides.LogLevel
+	}
+	if overrides.RootFS != "" {
+		cfg.RootFS = overrides.RootFS
+	}
+	if overrides.MonitorPort > 0 {
+		cfg.MonitorPort = overrides.MonitorPort
+	}
+
 	if cfg.BackendURL == "" {
 		return cfg, fmt.Errorf("backendUrl is required")
 	}
@@ -117,11 +164,25 @@ func getenvIntAny(keys []string, fallback int) int {
 }
 
 func hostnameOr(fallback string) string {
-	name, err := os.Hostname()
+	if name, err := os.Hostname(); err == nil && name != "" {
-	if err != nil || name == "" {
+		return name
+	}
 	return fallback
 }
-	return name
+
+// hostHostname reads the hostname from <rootFS>/etc/hostname. Used when
+// Monitor runs inside a container and wants the host's hostname rather
+// than the container's UTS namespace hostname (which docker randomizes
+// unless hostname: is set).
+func hostHostname(rootFS string) string {
+	if rootFS == "" {
+		return ""
+	}
+	buf, err := os.ReadFile(filepath.Join(rootFS, "etc", "hostname"))
+	if err != nil {
+		return ""
+	}
+	return strings.TrimSpace(string(buf))
 }
 
 func applyHostFSEnv(rootFS string) {

internal/telemetry/telemetry.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"log"
 	"net/http"
 	"os"
 	"os/exec"
@@ -35,6 +36,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) {
@@ -46,12 +51,15 @@ func BuildPayload(ctx context.Context, cfg config.Config) (Payload, error) {
 	}
 
 	cpuPct, err := cpu.PercentWithContext(ctx, time.Second, false)
-	if err == nil && len(cpuPct) > 0 {
+	if err != nil {
+		log.Printf("telemetry: cpu.Percent failed: %v", err)
+	} else if len(cpuPct) > 0 {
 		payload.CPUPct = round1(cpuPct[0])
 	}
 
-	vm, err := mem.VirtualMemoryWithContext(ctx)
+	if vm, err := mem.VirtualMemoryWithContext(ctx); err != nil {
-	if err == nil {
+		log.Printf("telemetry: mem.VirtualMemory failed: %v", err)
+	} else {
 		payload.MemPct = round1(vm.UsedPercent)
 	}
 
@@ -59,28 +67,33 @@ func BuildPayload(ctx context.Context, cfg config.Config) (Payload, error) {
 	if diskPath == "" {
 		diskPath = "/"
 	}
-	diskUsage, err := disk.UsageWithContext(ctx, diskPath)
+	if diskUsage, err := disk.UsageWithContext(ctx, diskPath); err != nil {
-	if err == nil {
+		log.Printf("telemetry: disk.Usage(%s) failed: %v", diskPath, err)
+	} else {
 		payload.DiskPct = round1(diskUsage.UsedPercent)
 	}
 
-	swapUsage, err := mem.SwapMemoryWithContext(ctx)
+	if swapUsage, err := mem.SwapMemoryWithContext(ctx); err != nil {
-	if err == nil {
+		log.Printf("telemetry: mem.SwapMemory failed: %v", err)
+	} else {
 		payload.SwapPct = round1(swapUsage.UsedPercent)
 	}
 
-	avg, err := gopsload.AvgWithContext(ctx)
+	if avg, err := gopsload.AvgWithContext(ctx); err != nil {
-	if err == nil {
+		log.Printf("telemetry: load.Avg failed: %v", err)
+	} else {
 		payload.LoadAvg = []float64{round2(avg.Load1), round2(avg.Load5), round2(avg.Load15)}
 	}
 
-	hostInfo, err := host.InfoWithContext(ctx)
+	if hostInfo, err := host.InfoWithContext(ctx); err != nil {
-	if err == nil {
+		log.Printf("telemetry: host.Info failed: %v", err)
+	} else {
 		payload.UptimeSeconds = hostInfo.Uptime
 	}
 
-	nginxInstalled, nginxSites, err := detectNginx(cfg.RootFS)
+	if nginxInstalled, nginxSites, err := detectNginx(cfg.RootFS); err != nil {
-	if err == nil {
+		log.Printf("telemetry: detectNginx failed: %v", err)
+	} else {
 		payload.NginxInstalled = nginxInstalled
 		payload.NginxSites = nginxSites
 	}
@@ -94,7 +107,7 @@ func Send(ctx context.Context, client *http.Client, cfg config.Config, payload P
 		return fmt.Errorf("marshal payload: %w", err)
 	}
 
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, strings.TrimRight(cfg.BackendURL, "/")+"/monitor/server/heartbeat-v2", strings.NewReader(string(body)))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, strings.TrimRight(cfg.BackendURL, "/")+"/monitor/server/heartbeat", strings.NewReader(string(body)))
 	if err != nil {
 		return fmt.Errorf("build request: %w", err)
 	}