unifi-network（统一网络）

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

• Tested Endpoints — Full catalog of verified read-only API calls