UniFi 网络监控技能

通过本地 UniFi OS 网关 API 监控和查询您的 UniFi 网络（已在 Cloud Gateway Max 上测试）。

目的

此技能提供只读访问您 UniFi 网络的操作数据：

• 设备（AP、交换机、网关）状态和健康状况
• 活动客户端（谁连接到了哪里）
• 网络健康概览
• 流量洞察（通过 DPI 识别的热门应用）
• 最近的告警和事件

所有操作均为仅 GET 请求，安全适用于监控/报告。

设置

创建凭据文件：~/.clawdbot/credentials/unifi/config.json

{
  "url": "https://10.1.0.1",
  "username": "api",
  "password": "YOUR_PASSWORD",
  "site": "default"
}

• url：您的 UniFi OS 网关 IP/主机名（HTTPS）
• username：本地 UniFi OS 管理员用户名
• 密码：本地 UniFi OS 管理员密码
• 站点：站点名称（通常为默认）

命令

所有命令都支持可选的json参数，用于原始 JSON 输出（默认为人类可读的表格）。

网络仪表板

所有网络统计数据的综合视图（健康状态、设备、客户端、网络、DPI 等）：

bash scripts/dashboard.sh
bash scripts/dashboard.sh json  # Raw JSON for all sections

输出：包含所有指标的完整 ASCII 仪表板。

列出设备

显示所有 UniFi 设备（AP、交换机、网关）：

bash scripts/devices.sh
bash scripts/devices.sh json  # Raw JSON

输出：设备名称、型号、IP、状态、运行时间、连接的客户端

列出活跃客户端

显示当前连接的设备：

bash scripts/clients.sh
bash scripts/clients.sh json  # Raw JSON

输出：主机名、IP、MAC、接入点、信号强度、接收/发送速率

健康摘要

全站健康状态：

bash scripts/health.sh
bash scripts/health.sh json  # Raw JSON

输出：子系统状态（WAN、LAN、WLAN），数量统计（在线/已采纳/断开连接）

热门应用程序（DPI）

按应用程序统计的带宽消耗排名：

bash scripts/top-apps.sh
bash scripts/top-apps.sh 15  # Show top 15 (default: 10)

输出：应用程序名称、类别、接收/发送/总流量（以GB为单位）

近期告警

近期告警与事件：

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/networkAPI 路径
• 所有调用均为只读的 GET 请求
• 已测试的端点记录在references/unifi-readonly-endpoints.md

参考

• 已测试的端点— 在您的 Cloud Gateway Max 上已验证的只读 API 调用的完整目录