UniFi 网络监控技能

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

目的

本技能提供对 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 # 所有部分的原始 JSON

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

列出设备

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

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

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

列出活跃客户端

显示当前连接的客户端：

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

输出： 主机名、IP、MAC、AP、信号强度、RX/TX 速率

健康摘要

站点范围的健康状态：

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

输出： 子系统状态（WAN、LAN、WLAN）、计数（在线/已采用/已断开）

应用排名（DPI）

按应用排名的带宽消耗大户：

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

输出： 应用名称、类别、RX/TX/总流量（GB）

工作流程

当用户询问 UniFi 相关问题时：

1. 我的网络上有什么？ → 运行 bash scripts/devices.sh + bash scripts/clients.sh
一切正常吗？ → 运行 bash scripts/health.sh
有什么问题吗？ → 运行 bash scripts/alerts.sh
什么在占用带宽？ → 运行 bash scripts/top-apps.sh
给我看仪表盘 或常规检查 → 运行 bash scripts/dashboard.sh

在向用户展示结果前，务必确认输出看起来合理（检查认证失败、空数据等）。

注意事项

- 需要网络访问您的 UniFi 网关
使用 UniFi OS 登录 + /proxy/network API 路径
所有调用均为只读 GET 请求
已测试的端点记录在 references/unifi-readonly-endpoints.md 中

参考

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

unifiUniFi网络查询

unifi

UniFi Network Monitoring Skill

Purpose

Setup

Commands

Network Dashboard

List Devices

List Active Clients

Health Summary

Top Applications (DPI)

Recent Alerts

Workflow

Notes

Reference

UniFi 网络监控技能

目的

设置