186 lines
5.8 KiB
Markdown
186 lines
5.8 KiB
Markdown
# 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": {
|
|
"harbor-forge": {
|
|
"enabled": true,
|
|
"config": {
|
|
"enabled": true,
|
|
"backendUrl": "https://monitor.hangman-lab.top",
|
|
"identifier": "my-server-01",
|
|
"apiKey": "your-api-key-here",
|
|
"monitorPort": 9100,
|
|
"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 |
|
|
| `monitorPort` | number | `9100`（示例） | 本地桥接端口；插件通过 `127.0.0.1:<monitorPort>` 与 HarborForge.Monitor 通信 |
|
|
| `reportIntervalSec` | number | `30` | 报告间隔（秒） |
|
|
| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
|
|
| `logLevel` | string | `"info"` | 日志级别: debug/info/warn/error |
|
|
|
|
## Monitor 本地桥接
|
|
|
|
当插件配置了 `monitorPort`，并且 HarborForge.Monitor 也以相同的 `MONITOR_PORT` 启动时：
|
|
|
|
- Monitor 会在 `127.0.0.1:<monitorPort>` 暴露本地桥接服务
|
|
- 插件可探测 `GET /health`
|
|
- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry`
|
|
- 若桥接端口未配置或不可达，插件仍然正常工作，只是不会拿到 Monitor 的宿主机遥测补充数据
|
|
|
|
这条链路是**可选增强**，不是插件或 Monitor 心跳上报的前置依赖。
|
|
|
|
## 收集的指标
|
|
|
|
### 系统指标
|
|
- 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) - 原始设计文档
|