feat: reorganize to standard OpenClaw plugin structure

New structure:
├── package.json                 # Root package
├── README.md                    # Documentation
├── plugin/                      # OpenClaw plugin
│   ├── openclaw.plugin.json     # Plugin manifest
│   ├── index.ts                 # Plugin entry (TypeScript)
│   ├── package.json
│   └── tsconfig.json
├── server/                      # Telemetry sidecar
│   └── telemetry.mjs
├── skills/                      # OpenClaw skills
└── scripts/
    └── install.mjs              # Installation script

Matches PaddedCell project structure.
Provides install.mjs with build/install/configure/uninstall commands.
This commit is contained in:
zhi
2026-03-19 13:51:19 +00:00
parent a148c11e50
commit 0debe835b4
8 changed files with 472 additions and 134 deletions

113
README.md
View File

@@ -2,20 +2,39 @@
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 (index.mjs) │ │
│ │ HarborForge.OpenclawPlugin/plugin/ │ │
│ │ - 生命周期管理 (启动/停止) │ │
│ │ - 配置管理 │ │
│ └───────────────────────────────────────────┘ │
│ │ │
│ ▼ 启动 sidecar
│ ▼ 启动 telemetry server
│ ┌───────────────────────────────────────────┐ │
│ │ Sidecar (sidecar/server.mjs) │ │
│ │ HarborForge.OpenclawPlugin/server/ │ │
│ │ - 独立 Node 进程 │ │
│ │ - 收集系统指标 │ │
│ │ - 收集 OpenClaw 状态 │ │
@@ -31,26 +50,35 @@ OpenClaw 插件,将服务器遥测数据流式传输到 HarborForge Monitor。
## 安装
### 1. 复制插件到 OpenClaw 插件目录
### 快速安装
```bash
# 找到 OpenClaw 插件目录
# 通常是 ~/.openclaw/plugins/ 或 /usr/lib/node_modules/openclaw/plugins/
# 克隆仓库
git clone https://git.hangman-lab.top/zhi/HarborForge.OpenclawPlugin.git
cd HarborForge.OpenclawPlugin
# 复制插件
cp -r HarborForge.OpenclawPlugin ~/.openclaw/plugins/harborforge-monitor
# 运行安装脚本
node scripts/install.mjs
```
### 2. 在 HarborForge Monitor 中注册服务器
### 开发安装
1. 登录 HarborForge Monitor
2. 进入 Server Management
3. 点击 "Register New Server"
4. 获取 `challengeUuid`
```bash
# 仅构建不安装
node scripts/install.mjs --build-only
### 3. 配置 OpenClaw
# 指定 OpenClaw 路径
node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw
编辑 `~/.openclaw/openclaw.json`:
# 详细输出
node scripts/install.mjs --verbose
```
## 配置
1. 在 HarborForge Monitor 中注册服务器,获取 `challengeUuid`
2. 编辑 `~/.openclaw/openclaw.json`:
```json
{
@@ -68,7 +96,7 @@ cp -r HarborForge.OpenclawPlugin ~/.openclaw/plugins/harborforge-monitor
}
```
### 4. 重启 OpenClaw Gateway
3. 重启 OpenClaw Gateway:
```bash
openclaw gateway restart
@@ -79,7 +107,7 @@ openclaw gateway restart
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `enabled` | boolean | `true` | 是否启用插件 |
| `backendUrl` | string | `"https://monitor.hangman-lab.top"` | Monitor 后端地址 |
| `backendUrl` | string | `https://monitor.hangman-lab.top` | Monitor 后端地址 |
| `identifier` | string | 自动检测 hostname | 服务器标识符 |
| `challengeUuid` | string | 必填 | 注册挑战 UUID |
| `reportIntervalSec` | number | `30` | 报告间隔(秒) |
@@ -103,52 +131,37 @@ openclaw gateway restart
- Agent 数量
- Agent 列表 (id, name, status)
## 故障排查
### 查看日志
## 卸载
```bash
# 查看 Gateway 日志
openclaw gateway logs | grep HF-Monitor
# 或者直接查看 sidecar 输出(如果独立运行)
node sidecar/server.mjs 2>&1 | tee monitor.log
node scripts/install.mjs --uninstall
```
### 检查状态
在 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
cd plugin
npm install
npm run build
```
### 本地测试 telemetry server
```bash
cd server
HF_MONITOR_CHALLENGE_UUID=test-uuid \
HF_MONITOR_BACKEND_URL=http://localhost:8000 \
HF_MONITOR_LOG_LEVEL=debug \
node server.mjs
node telemetry.mjs
```
## 依赖
- Node.js 18+
- OpenClaw Gateway
## 文档
- [监控连接器规划](./docs/monitor-server-connector-plan.md) - 原始设计文档