UniFi Network 监控技能

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

用途

该技能提供对您的 UniFi 网络运行数据的只读访问权限：

• 设备（AP、交换机、网关）状态与健康状况
• 活跃客户端（谁在何处接入）
• 网络健康概览
• 流量洞察（基于 DPI 的热门应用）
• 近期告警与事件

所有操作均为仅 GET 请求，适用于监控与报表场景，安全无副作用。

配置

创建凭证文件：~/.openclaw/credentials/unifi.json

{
  "host": "your-gateway-ip",
  "username": "your_username",
  "password": "your_password",
  "note": "Local Read-Only account on UniFi OS"
}

注意：URL 必须使用 HTTPS，并指向您的 UniFi 网关。site 在家庭部署中通常为 default。

• host：您的 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 地址、关联 AP、信号强度、RX/TX 速率

健康状态汇总

全站点范围的健康状态：

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 名）

输出：应用名称、所属类别、RX/TX/总计流量（单位：GB）

近期告警

近期产生的告警与事件：

bash scripts/alerts.sh
bash scripts/alerts.sh 50  # 显示最近 50 条（默认为最近 20 条）

输出：时间戳、告警键（alarm key）、消息内容、受影响设备

工作流

当用户询问有关 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 请求
• 已测试的 API 终端点详见 references/unifi-readonly-endpoints.md

参考文档

• 已测试终端点 —— 已验证的只读 API 调用完整清单