介绍
# UniFi Network Monitoring Skill
通过本地 UniFi OS 网关 API 监控和查询您的 UniFi 网络（已在 Cloud Gateway Max 上测试）。
## 用途
此技能提供对 UniFi 网络运营数据的**只读**访问权限： - 设备（AP、交换机、网关）状态和健康状况 - 活动客户端（谁连接到了哪里） - 网络健康状况概览 - 流量洞察（通过 DPI 获取热门应用） - 近期的告警和事件
所有操作均为 **仅限 GET**，对于监控/报告是安全的。
## 设置
创建凭证文件：`~/.clawdbot/credentials/unifi/config.json`
```json { "url": "https://10.1.0.1", "username": "api", "password": "YOUR_PASSWORD", "site": "default" } ```
- `url`：您的 UniFi OS 网关 IP/主机名（HTTPS） - `username`：本地 UniFi OS 管理员用户名 - `password`：本地 UniFi OS 管理员密码 - `site`：站点名称（通常为 `default`）
## 命令
所有命令都支持可选的 `json` 参数，用于输出原始 JSON（默认为人类可读的表格格式）。
### 网络仪表板
所有网络统计数据的综合视图（健康状况、设备、客户端、网络、DPI 等）：
```bash bash scripts/dashboard.sh bash scripts/dashboard.sh json # Raw JSON for all sections ```
**输出：** 包含所有指标的完整 ASCII 仪表板。
### 列出设备
显示所有 UniFi 设备（AP、交换机、网关）：
```bash bash scripts/devices.sh bash scripts/devices.sh json # Raw JSON ```
**输出：** 设备名称、型号、IP、状态、运行时间、已连接客户端数
### 列出活动客户端
显示当前连接的用户：
```bash bash scripts/clients.sh bash scripts/clients.sh json # Raw JSON ```
**输出：** 主机名、IP、MAC、AP、信号强度、RX/TX 速率
### 健康状况摘要
站点范围内的健康状况：
```bash bash scripts/health.sh bash scripts/health.sh json # Raw JSON ```
**输出：** 子系统状态（WAN、LAN、WLAN）、计数（在线/已采纳/已断开）
### 热门应用 (DPI)
按应用划分的带宽消耗大户：
```bash bash scripts/top-apps.sh bash scripts/top-apps.sh 15 # Show top 15 (default: 10) ```
**输出：** 应用名称、类别、RX/TX/总流量（单位为 GB）
### 近期告警
近期的告警和事件：
```bash bash scripts/alerts.sh bash scripts/alerts.sh 50 # Show last 50 (default: 20) ```
**输出：** 时间戳、告警键、消息、受影响的设备
## 工作流程
当用户询问关于 UniFi 的信息时：
1. **“我的网络里有什么？”** → 运行 `bash scripts/devices.sh` + `bash scripts/clients.sh` 2. **“一切都正常吗？”** → 运行 `bash scripts/health.sh` 3. **“有什么问题吗？”** → 运行 `bash scripts/alerts.sh` 4. **“谁在占用带宽？”** → 运行 `bash scripts/top-apps.sh` 5. **“给我看仪表板”** 或常规检查 → 运行 `bash scripts/dashboard.sh`
在向用户展示结果之前，请务必确认输出看起来合理（检查认证失败、空数据等）。
## 注意事项
- 需要网络访问权限以连接到您的 UniFi 网关 - 使用 UniFi OS 登录 + `/proxy/network` API 路径 - 所有调用均为 **只读 GET 请求** - 经过测试的端点记录在 `references/unifi-readonly-endpoints.md` 中
## 参考
- [经测试的端点](references/unifi-readonly-endpoints.md) — 您的 Cloud Gateway Max 上经过验证的只读 API 调用完整目录