360 Secure SkillHub
360 安全技能中心

UniFi Network

该 Skill 通过 bash 脚本调用本地 UniFi OS 网关 API，以只读方式获取网络设备、活动客户端、站点健康、DPI 应用流量与最近告警，并输出人类可读表格或原始 JSON；需配置含网关地址与本地账号的凭据文件，依赖 curl 与 jq。

ricanwarfare
ricanwarfare
热度 46.92
最近更新 2026-05-11 17:40:25
分类：自动化依赖：代码执行 / 第三方 API / 读写文件应用场景：自动化脚本 / 工作流 / 报告撰写

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add unifi-network
Metadata
name
unifi-network
slug
unifi-network
description
Query and monitor UniFi network via local gateway API (Cloud Gateway Ultra / UniFi OS). Use when the user asks to "check UniFi", "list UniFi devices", "show who's on the network", "UniFi clients", "UniFi health", "top apps", "network alerts", "UniFi DPI", or mentions UniFi monitoring/status/dashboard.
version
1.0.0
metadata
{"openclaw":{"emoji":"📡","requires":{"bins":["curl","jq"]}}}

UniFi Network Monitoring Skill

Monitor and query your UniFi network via the local UniFi OS gateway API (tested on Cloud Gateway Ultra).

Purpose

This skill provides read-only access to your UniFi network's operational data:

  • Devices (APs, switches, gateway) status and health
  • Active clients (who's connected where)
  • Network health overview
  • Traffic insights (top applications via DPI)
  • Recent alarms and events

All operations are GET-only and safe for monitoring/reporting.

Setup

Create the credentials file: ~/.openclaw/credentials/unifi.json

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

Note: The URL must use HTTPS and point to your UniFi gateway. The site is usually default for home setups.

  • host: Your UniFi OS gateway IP/hostname (without https://)
  • username: Local UniFi OS admin username
  • password: Local UniFi OS admin password
  • site: Site name (usually default)

Commands

All commands support optional json argument for raw JSON output (default is human-readable table).

Network Dashboard

Comprehensive view of all network stats (Health, Devices, Clients, Networks, DPI, etc.):

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

Output: Full ASCII dashboard with all metrics.

List Devices

Shows all UniFi devices (APs, switches, gateway):

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

Output: Device name, model, IP, state, uptime, connected clients

List Active Clients

Shows who's currently connected:

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

Output: Hostname, IP, MAC, AP, signal strength, RX/TX rates

Health Summary

Site-wide health status:

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

Output: Subsystem status (WAN, LAN, WLAN), counts (up/adopted/disconnected)

Top Applications (DPI)

Top bandwidth consumers by application:

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

Output: App name, category, RX/TX/total traffic in GB

Recent Alerts

Recent alarms and events:

bash scripts/alerts.sh
bash scripts/alerts.sh 50  # Show last 50 (default: 20)

Output: Timestamp, alarm key, message, affected device

Workflow

When the user asks about UniFi:

  1. "What's on my network?" → Run bash scripts/devices.sh + bash scripts/clients.sh
  2. "Is everything healthy?" → Run bash scripts/health.sh
  3. "Any problems?" → Run bash scripts/alerts.sh
  4. "What's using bandwidth?" → Run bash scripts/top-apps.sh
  5. "Show me a dashboard" or general checkup → Run bash scripts/dashboard.sh

Always confirm the output looks reasonable before presenting it to the user (check for auth failures, empty data, etc.).

Notes

  • Requires network access to your UniFi gateway
  • Uses UniFi OS login + /proxy/network API path
  • All calls are read-only GET requests
  • Tested endpoints are documented in references/unifi-readonly-endpoints.md

Reference