zhi
a148c11e50
Architecture: - openclaw.plugin.json: Plugin manifest with config schema - index.mjs: Plugin entry, lifecycle hooks (gateway:start/stop) - sidecar/server.mjs: Independent Node process for telemetry Features: - Collects system metrics (CPU, memory, disk, load, uptime) - Collects OpenClaw status (version, agents) - HTTP heartbeat to HarborForge Monitor - Config via ~/.openclaw/openclaw.json - Sidecar auto-starts/stops with Gateway Config options: - enabled, backendUrl, identifier - challengeUuid (required, from Monitor registration) - reportIntervalSec, httpFallbackIntervalSec - logLevel Provides tool: harborforge_monitor_status
155 lines
4.7 KiB
Markdown
155 lines
4.7 KiB
Markdown
# 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) - 原始设计文档
|