168 lines
3.9 KiB
Markdown
168 lines
3.9 KiB
Markdown
# HarborForge OpenClaw Plugin
|
||
|
||
OpenClaw 插件：向 HarborForge Monitor 暴露 OpenClaw 侧元数据，并提供可选的本地桥接能力；安装时也可顺带安装 `hf` CLI。
|
||
|
||
## 当前状态
|
||
|
||
- 插件注册名：`harbor-forge`
|
||
- 旧 sidecar `server/` 架构已移除
|
||
- 监控桥接走本地 `monitor_port`
|
||
- 安装脚本支持 `--install-cli`
|
||
- `skills/hf/` 仅在 `--install-cli` 时一并安装
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
HarborForge.OpenclawPlugin/
|
||
├── package.json
|
||
├── README.md
|
||
├── plugin/
|
||
│ ├── openclaw.plugin.json
|
||
│ ├── index.ts
|
||
│ ├── core/
|
||
│ │ ├── config.ts
|
||
│ │ ├── managed-monitor.ts
|
||
│ │ └── monitor-bridge.ts
|
||
│ ├── hooks/
|
||
│ │ ├── gateway-start.ts
|
||
│ │ └── gateway-stop.ts
|
||
│ └── package.json
|
||
├── skills/
|
||
│ └── hf/
|
||
│ └── SKILL.md
|
||
└── scripts/
|
||
└── install.mjs
|
||
```
|
||
|
||
## 安装
|
||
|
||
### 普通安装
|
||
|
||
```bash
|
||
node scripts/install.mjs
|
||
```
|
||
|
||
这会：
|
||
- 构建并安装 OpenClaw 插件
|
||
- 复制常规 skills
|
||
- **不会**安装 `hf` 二进制
|
||
- **不会**复制 `skills/hf/`
|
||
|
||
### 安装插件 + `hf` CLI
|
||
|
||
```bash
|
||
node scripts/install.mjs --install-cli
|
||
```
|
||
|
||
这会额外：
|
||
- 构建 `HarborForge.Cli`
|
||
- 安装 `hf` 到 `~/.openclaw/bin/hf`
|
||
- `chmod +x ~/.openclaw/bin/hf`
|
||
- 复制 `skills/hf/` 到 OpenClaw profile skills 目录
|
||
|
||
### 常用选项
|
||
|
||
```bash
|
||
# 仅构建
|
||
node scripts/install.mjs --build-only
|
||
|
||
# 指定 OpenClaw profile
|
||
node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw
|
||
|
||
# 详细日志
|
||
node scripts/install.mjs --verbose
|
||
|
||
# 卸载
|
||
node scripts/install.mjs --uninstall
|
||
```
|
||
|
||
## 配置
|
||
|
||
编辑 `~/.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",
|
||
"monitor_port": 9100,
|
||
"reportIntervalSec": 30,
|
||
"httpFallbackIntervalSec": 60,
|
||
"logLevel": "info"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
然后重启：
|
||
|
||
```bash
|
||
openclaw gateway restart
|
||
```
|
||
|
||
## 配置项
|
||
|
||
| 选项 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `enabled` | boolean | `true` | 是否启用插件 |
|
||
| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge Monitor 后端地址 |
|
||
| `identifier` | string | 主机名 | 服务器标识符 |
|
||
| `apiKey` | string | 无 | HarborForge Monitor 生成的服务器 API Key |
|
||
| `monitor_port` | number | 无 | 本地桥接端口；插件通过 `127.0.0.1:<monitor_port>` 与 HarborForge.Monitor 通信 |
|
||
| `reportIntervalSec` | number | `30` | 报告间隔（秒） |
|
||
| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） |
|
||
| `logLevel` | string | `info` | 日志级别：`debug` / `info` / `warn` / `error` |
|
||
|
||
## 本地桥接说明
|
||
|
||
当插件配置了 `monitor_port`，并且 HarborForge.Monitor 也使用相同的 `MONITOR_PORT` 时：
|
||
|
||
- Monitor 在 `127.0.0.1:<MONITOR_PORT>` 提供本地桥接服务
|
||
- 插件可探测 `GET /health`
|
||
- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry`
|
||
- 如果桥接端口未配置或不可达，插件仍可正常运行
|
||
|
||
也就是说，这条链路是**可选增强**，不是插件启动或 Monitor 心跳的前置条件。
|
||
|
||
## 插件提供的信息
|
||
|
||
### OpenClaw 元数据
|
||
- OpenClaw version
|
||
- plugin version
|
||
- 标识符 / 主机名
|
||
- 时间戳
|
||
|
||
### 系统快照
|
||
- uptime
|
||
- memory total/free/used/usagePercent
|
||
- load avg1/avg5/avg15
|
||
- platform
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
cd plugin
|
||
npm install
|
||
npm run build
|
||
```
|
||
|
||
## 依赖
|
||
|
||
- Node.js 18+
|
||
- OpenClaw Gateway
|
||
- Go 1.20+（仅 `--install-cli` 需要）
|
||
|
||
## 相关提示
|
||
|
||
- 安装 `hf` 后，建议把 `~/.openclaw/bin` 加到 `PATH`
|
||
- Agent 使用 `hf` 时，优先试 `hf --help-brief`
|
||
- 完整命令树看 `hf --help`
|