UniFi 集成 API

使用本技能通过 UniFi API 密钥实现只读式 UniFi 监控。

配置

创建凭证文件：

~/.clawdbot/credentials/unifi/config.json

示例：

{
  "url": "https://gateway.local",
  "token": "YOUR_API_KEY",
  "site": "default"
}

说明：

• token 是 UniFi API 密钥
• 请求使用请求头 X-API-KEY:
• 脚本会自动从 /proxy/network/integration/v1/sites 解析站点 ID
• site 用于经典只读端点，例如 stat/health、stat/alarm、rest/networkconf 和 rest/wlanconf

命令

站点

bash scripts/sites.sh
bash scripts/sites.sh json

列出可用的 UniFi 站点及其 ID。

健康状态

bash scripts/health.sh
bash scripts/health.sh json

显示紧凑摘要，包括设备总数、在线/离线数量、角色分布及客户端数量。

设备

bash scripts/devices.sh
bash scripts/devices.sh json

显示 UniFi 基础设施设备，含型号、IP 地址、状态、固件版本及功能角色。

客户端

bash scripts/clients.sh
bash scripts/clients.sh json

显示已连接客户端，含类型、IP 地址、MAC 地址、连接时间及上行设备 ID。

仪表板

bash scripts/dashboard.sh
bash scripts/dashboard.sh json

显示综合概览，包括：

• 站点与控制台信息
• UniFi 版本
• 健康子系统状态
• 设备列表
• 网络配置
• 无线局域网（WLAN）配置
• 活跃客户端 Top 列表
• 近期告警摘要

告警 / alarms

bash scripts/alerts.sh

显示近期 UniFi 告警。若无告警，则明确提示“暂无近期告警”。

Top 应用 / DPI

bash scripts/top-apps.sh
bash scripts/top-apps.sh 15

若网关返回 DPI 数据，则按深度包检测（DPI）结果展示流量占比最高的应用；否则提示“当前暂无 DPI 数据可用”。

当前支持的端点

已在该网关上验证可用的端点：

• /proxy/network/integration/v1/sites
• /proxy/network/integration/v1/sites/{siteId}/devices
• /proxy/network/integration/v1/sites/{siteId}/clients
• /proxy/network/api/s/{site}/stat/health
• /proxy/network/api/s/{site}/stat/sysinfo
• /proxy/network/api/s/{site}/stat/alarm
• /proxy/network/api/s/{site}/stat/sitedpi
• /proxy/network/api/s/{site}/rest/networkconf
• /proxy/network/api/s/{site}/rest/wlanconf

注意事项：

• 告警 / 事件接口可能合法地返回零条结果
• DPI 接口即使可访问，也可能返回空载荷
• 部分管理 / 配置类接口会暴露敏感数据；除非明确需要原始数据，否则请避免输出完整原始响应体

工作流

当用户提出以下请求时：

• “检查 UniFi” / “仪表板” → 执行 bash scripts/dashboard.sh
• “一切是否正常？” → 执行 bash scripts/health.sh
• “显示设备” → 执行 bash scripts/devices.sh
• “谁连在了网络上？” / “客户端” → 执行 bash scripts/clients.sh
• “有哪些站点？” → 执行 bash scripts/sites.sh
• “有告警吗？” / “告警” → 执行 bash scripts/alerts.sh
• “Top 应用” / “流量” / “DPI” → 执行 bash scripts/top-apps.sh

在向用户反馈前，请始终对响应进行合理性校验：

• 确认 API 返回的是合法 JSON 格式
• 确认各项计数在合理范围内
• 若告警或 DPI 数据为空，应如实说明“暂无数据”，而非将其误判为认证失败或端点不可达
• 除非用户明确要求原始细节，否则请避免将敏感的管理类响应体直接返回给用户