# HarborForge OpenClaw Plugin

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

## 当前状态

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

## 项目结构

```text
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
```

## 安装

### 普通安装

```bash
node scripts/install.mjs
```

这会：
- 构建并安装 OpenClaw 插件
- 复制常规 skills
- **不会**安装 `hf` 二进制
- **不会**复制 `skills/hf/`

### 安装插件 + `hf` CLI

```bash
node scripts/install.mjs --install-cli
```

这会额外：
- 构建 `HarborForge.Cli`
- 安装 `hf` 到 `~/.openclaw/bin/hf`
- `chmod +x ~/.openclaw/bin/hf`
- 复制 `skills/hf/` 到 OpenClaw profile skills 目录

### 常用选项

```bash
# 仅构建
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`：

```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"
        }
      }
    }
  }
}
```

然后重启：

```bash
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

## 开发

```bash
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`