# HarborForge OpenClaw Plugin

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

## 架构

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

## 安装

### 1. 复制插件到 OpenClaw 插件目录

```bash
# 找到 OpenClaw 插件目录
# 通常是 ~/.openclaw/plugins/ 或 /usr/lib/node_modules/openclaw/plugins/

# 复制插件
cp -r HarborForge.OpenclawPlugin ~/.openclaw/plugins/harborforge-monitor
```

### 2. 在 HarborForge Monitor 中注册服务器

1. 登录 HarborForge Monitor
2. 进入 Server Management
3. 点击 "Register New Server"
4. 获取 `challengeUuid`

### 3. 配置 OpenClaw

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

```json
{
  "plugins": {
    "harborforge-monitor": {
      "enabled": true,
      "backendUrl": "https://monitor.hangman-lab.top",
      "identifier": "my-server-01",
      "challengeUuid": "your-challenge-uuid-here",
      "reportIntervalSec": 30,
      "httpFallbackIntervalSec": 60,
      "logLevel": "info"
    }
  }
}
```

### 4. 重启 OpenClaw Gateway

```bash
openclaw gateway restart
```

## 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | boolean | `true` | 是否启用插件 |
| `backendUrl` | string | `"https://monitor.hangman-lab.top"` | Monitor 后端地址 |
| `identifier` | string | 自动检测 hostname | 服务器标识符 |
| `challengeUuid` | string | 必填 | 注册挑战 UUID |
| `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
# 查看 Gateway 日志
openclaw gateway logs | grep HF-Monitor

# 或者直接查看 sidecar 输出（如果独立运行）
node sidecar/server.mjs 2>&1 | tee monitor.log
```

### 检查状态

在 OpenClaw 对话中:

```
使用 harborforge_monitor_status 工具检查插件状态
```

### 常见问题

1. **challengeUuid 未设置**
   - 错误: `Missing required config: challengeUuid`
   - 解决: 在 Monitor 中注册服务器并配置 challengeUuid

2. **Sidecar 无法启动**
   - 检查 Node.js 版本 (>=18)
   - 检查 `sidecar/server.mjs` 是否存在

3. **无法连接到 Monitor**
   - 检查 `backendUrl` 配置
   - 检查网络连接和防火墙

## 开发

### 本地测试 sidecar

```bash
cd sidecar
HF_MONITOR_CHALLENGE_UUID=test-uuid \
HF_MONITOR_BACKEND_URL=http://localhost:8000 \
HF_MONITOR_LOG_LEVEL=debug \
node server.mjs
```

## 文档

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