HarborForge.OpenclawPlugin/README.md

HarborForge OpenClaw Plugin

OpenClaw 插件：向 HarborForge Monitor 暴露 OpenClaw 侧元数据，并提供可选的本地桥接能力；安装时也可顺带安装 hf CLI。

当前状态

• 插件注册名：harbor-forge
• 旧 sidecar server/ 架构已移除
• 监控桥接走本地 monitor_port
• 安装脚本支持 --install-cli
• skills/hf/ 仅在 --install-cli 时一并安装

项目结构

HarborForge.OpenclawPlugin/
├── package.json
├── README.md
├── plugin/
│   ├── openclaw.plugin.json
│   ├── index.ts
│   ├── core/
│   │   ├── config.ts
│   │   ├── managed-monitor.ts
│   │   └── monitor-bridge.ts
│   ├── hooks/
│   │   ├── gateway-start.ts
│   │   └── gateway-stop.ts
│   └── package.json
├── skills/
│   └── hf/
│       └── SKILL.md
└── scripts/
    └── install.mjs

安装

普通安装

node scripts/install.mjs

这会：

• 构建并安装 OpenClaw 插件
• 复制常规 skills
• 不会安装 hf 二进制
• 不会复制 skills/hf/

安装插件 + hf CLI

node scripts/install.mjs --install-cli

这会额外：

• 构建 HarborForge.Cli
• 安装 hf 到 ~/.openclaw/bin/hf
• chmod +x ~/.openclaw/bin/hf
• 复制 skills/hf/ 到 OpenClaw profile skills 目录

常用选项

# 仅构建
node scripts/install.mjs --build-only

# 指定 OpenClaw profile
node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw

# 详细日志
node scripts/install.mjs --verbose

# 卸载
node scripts/install.mjs --uninstall

配置

编辑 ~/.openclaw/openclaw.json：

{
  "plugins": {
    "entries": {
      "harbor-forge": {
        "enabled": true,
        "config": {
          "enabled": true,
          "backendUrl": "https://monitor.hangman-lab.top",
          "identifier": "my-server-01",
          "apiKey": "your-api-key-here",
          "monitor_port": 9100,
          "reportIntervalSec": 30,
          "httpFallbackIntervalSec": 60,
          "logLevel": "info"
        }
      }
    }
  }
}

然后重启：

openclaw gateway restart

配置项

选项	类型	默认值	说明
enabled	boolean	true	是否启用插件
backendUrl	string	https://monitor.hangman-lab.top	HarborForge Monitor 后端地址
identifier	string	主机名	服务器标识符
apiKey	string	无	HarborForge Monitor 生成的服务器 API Key
monitor_port	number	无	本地桥接端口；插件通过 127.0.0.1:<monitor_port> 与 HarborForge.Monitor 通信
reportIntervalSec	number	30	报告间隔（秒）
httpFallbackIntervalSec	number	60	HTTP 回退间隔（秒）
logLevel	string	info	日志级别：debug / info / warn / error

本地桥接说明

当插件配置了 monitor_port，并且 HarborForge.Monitor 也使用相同的 MONITOR_PORT 时：

• Monitor 在 127.0.0.1:<MONITOR_PORT> 提供本地桥接服务
• 插件可探测 GET /health
• 插件工具 harborforge_monitor_telemetry 可读取 GET /telemetry
• 如果桥接端口未配置或不可达，插件仍可正常运行

也就是说，这条链路是可选增强，不是插件启动或 Monitor 心跳的前置条件。

插件提供的信息

OpenClaw 元数据

• OpenClaw version
• plugin version
• 标识符 / 主机名
• 时间戳

系统快照

• uptime
• memory total/free/used/usagePercent
• load avg1/avg5/avg15
• platform

开发

cd plugin
npm install
npm run build

依赖

• Node.js 18+
• OpenClaw Gateway
• Go 1.20+（仅 --install-cli 需要）

相关提示

• 安装 hf 后，建议把 ~/.openclaw/bin 加到 PATH
• Agent 使用 hf 时，优先试 hf --help-brief
• 完整命令树看 hf --help