名称： unifi
描述： 通过本地网关 API（Cloud Gateway Max / UniFi OS）查询和监控 UniFi 网络。当用户提出“检查 UniFi”、“列出 UniFi 设备”、“显示谁在网络上”、“UniFi 客户端”、“UniFi 健康状态”、“热门应用”、“网络告警”、“UniFi DPI”或提及 UniFi 监控/状态/仪表板时使用。
版本： 1.0.1
元数据：
clawdbot:
emoji: "📡"
requires:
bins: ["curl", "jq"]

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 管理员用户名
• password：本地 UniFi OS 管理员密码
• site：站点名称（通常为 default）

命令列表

所有命令均支持可选的 json 参数以输出原始 JSON 数据（默认为人类可读的表格格式）。

网络仪表板

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

bash scripts/dashboard.sh
bash scripts/dashboard.sh json  # 所有部分的原始 JSON 数据

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

列出设备

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

bash scripts/devices.sh
bash scripts/devices.sh json  # 原始 JSON 数据

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

列出活跃客户端

显示当前连接的客户端：

bash scripts/clients.sh
bash scripts/clients.sh json  # 原始 JSON 数据

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

健康摘要

站点范围的健康状态：

bash scripts/health.sh
bash scripts/health.sh json  # 原始 JSON 数据

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

热门应用（DPI）

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

bash scripts/top-apps.sh
bash scripts/top-apps.sh 15  # 显示前 15 名（默认：10）

输出： 应用名称、类别、接收/发送/总流量（GB）。

近期告警

近期告警与事件：

bash scripts/alerts.sh
bash scripts/alerts.sh 50  # 显示最近 50 条（默认：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 中

参考文档

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