# HarborForge OpenClaw Plugin

OpenClaw 插件，将服务器遥测数据流式传输到 HarborForge Monitor。

## 项目结构

```
HarborForge.OpenclawPlugin/
├── package.json                 # 根 package.json
├── README.md                    # 本文档
├── plugin/                      # OpenClaw 插件代码
│   ├── openclaw.plugin.json     # 插件定义
│   ├── index.ts                 # 插件入口
│   ├── package.json             # 插件依赖
│   └── tsconfig.json            # TypeScript 配置
├── server/                      # Sidecar 服务器
│   └── telemetry.mjs            # 遥测数据收集和发送
├── skills/                      # OpenClaw 技能
│   └── (技能文件)
└── scripts/
    └── install.mjs              # 安装脚本
```

## 架构

```
┌─────────────────────────────────────────────────┐
│  OpenClaw Gateway                               │
│  ┌───────────────────────────────────────────┐  │
│  │  HarborForge.OpenclawPlugin/plugin/       │  │
│  │  - 生命周期管理 (启动/停止)                 │  │
│  │  - 配置管理                                │  │
│  └───────────────────────────────────────────┘  │
│              │                                   │
│              ▼ 启动 telemetry server             │
│  ┌───────────────────────────────────────────┐  │
│  │  HarborForge.OpenclawPlugin/server/       │  │
│  │  - 独立 Node 进程                          │  │
│  │  - 收集系统指标                            │  │
│  │  - 收集 OpenClaw 状态                      │  │
│  │  - 发送到 HarborForge Monitor              │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                        │
                        ▼ HTTP
              ┌─────────────────────┐
              │ HarborForge Monitor │
              └─────────────────────┘
```

## 安装

### 快速安装

```bash
# 克隆仓库
git clone https://git.hangman-lab.top/zhi/HarborForge.OpenclawPlugin.git
cd HarborForge.OpenclawPlugin

# 运行安装脚本
node scripts/install.mjs
```

### 开发安装

```bash
# 仅构建不安装
node scripts/install.mjs --build-only

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

# 详细输出
node scripts/install.mjs --verbose
```

## 配置

1. 在 HarborForge Monitor 中注册服务器，并生成 `apiKey`

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

```json
{
  "plugins": {
    "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"
        }
      }
    }
  }
}
```

3. 重启 OpenClaw Gateway:

```bash
openclaw gateway restart
```

## 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | boolean | `true` | 是否启用插件 |
| `backendUrl` | string | `https://monitor.hangman-lab.top` | Monitor 后端地址 |
| `identifier` | string | 自动检测 hostname | 服务器标识符 |
| `apiKey` | string | 必填 | HarborForge Monitor 生成的服务器 API Key |
| `reportIntervalSec` | number | `30` | 报告间隔（秒） |
| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
| `logLevel` | string | `"info"` | 日志级别: debug/info/warn/error |

## 收集的指标

### 系统指标
- CPU 使用率 (%)
- 内存使用率 (%)、已用/总量 (MB)
- 磁盘使用率 (%)、已用/总量 (GB)
- 交换分区使用率 (%)
- 系统运行时间 (秒)
- 1分钟平均负载
- 平台 (linux/darwin/win32)
- 主机名

### OpenClaw 指标
- OpenClaw 版本
- Agent 数量
- Agent 列表 (id, name, status)

## 卸载

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

## 开发

### 构建插件

```bash
cd plugin
npm install
npm run build
```

### 本地测试 telemetry server

```bash
cd server
HF_MONITOR_API_KEY=test-api-key \
HF_MONITOR_BACKEND_URL=http://localhost:8000 \
HF_MONITOR_LOG_LEVEL=debug \
node telemetry.mjs
```

## 依赖

- Node.js 18+
- OpenClaw Gateway

## 文档

- [监控连接器规划](./docs/monitor-server-connector-plan.md) - 原始设计文档