UniFi Network Advisor
Read-only skill covering two official UniFi API surfaces. All operations are GET-only — no writes, no mutations of any kind.
API surfaces
Everything goes through https://api.ui.com. No direct local connection required.
| Prefix | Surface | Proxied via | Env vars needed |
|---|---|---|---|
| SM | Site Manager | api.ui.com/v1/... | UNIFI_API_KEY |
| NET | Network Integration | api.ui.com/v1/connector/consoles/{hostId}/proxy/network/integration/v1/... | UNIFI_API_KEY (host/site resolved automatically) |
How to call the script
python3 {baseDir}/scripts/unifi.py <subcommand> [--site SITE] [--id ID] [--limit N] [--next-token TOKEN] [subcommand-specific flags]
Some subcommands require additional flags — see the table below. Use python3 {baseDir}/scripts/unifi.py list to see all subcommands with descriptions.
Subcommands
Site Manager (SM) — cloud, single API key
| Subcommand | Endpoint | Required flags | Description |
|---|---|---|---|
hosts | GET /v1/hosts | — | All UniFi OS consoles on the UI account |
host | GET /v1/hosts/{id} | --id | Console details |
sites | GET /v1/sites | — | All sites across all consoles |
cloud-devices | GET /v1/devices | — | All devices across all sites |
isp-metrics | GET /ea/isp-metrics/{type} | — | ISP performance metrics |
sdwan | GET /v1/sd-wan-configs | — | SD-WAN configurations |
sdwan-config | GET /v1/sd-wan-configs/{id} | --id | Specific SD-WAN config |
sdwan-status | GET /v1/sd-wan-configs/{id}/status | --id | SD-WAN deployment status |
Network Integration (NET) — proxied via api.ui.com, site resolved automatically
| Subcommand | Endpoint | Required flags | Description |
|---|---|---|---|
info | GET /v1/info | — | Controller version and capabilities |
net-sites | GET /v1/sites | — | Sites managed by this console |
devices | GET /v1/sites/{siteId}/devices | — | Adopted devices overview |
device | GET /v1/sites/{siteId}/devices/{id} | --id | Device details |
device-stats | GET /v1/sites/{siteId}/devices/{id}/statistics/latest | --id | Latest device statistics |
devices-pending | GET /v1/pending-devices | — | Devices pending adoption (console-scoped) |
clients | GET /v1/sites/{siteId}/clients | — | Connected clients overview |
client | GET /v1/sites/{siteId}/clients/{id} | --id | Client details |
networks | GET /v1/sites/{siteId}/networks | — | Networks overview |
network | GET /v1/sites/{siteId}/networks/{id} | --id | Network details |
network-refs | GET /v1/sites/{siteId}/networks/{id}/references | --id | What references a specific network (devices, clients, WiFi) |
wifi | GET /v1/sites/{siteId}/wifi/broadcasts | — | WiFi broadcast (SSID) overview |
wifi-details | GET /v1/sites/{siteId}/wifi/broadcasts/{id} | --id | WiFi broadcast details |
firewall-zones | GET /v1/sites/{siteId}/firewall/zones | — | Firewall zones |
firewall-zone | GET /v1/sites/{siteId}/firewall/zones/{id} | --id | Firewall zone details |
firewall-policies | GET /v1/sites/{siteId}/firewall/policies | — | Firewall policies |
firewall-policy | GET /v1/sites/{siteId}/firewall/policies/{id} | --id | Firewall policy details |
firewall-ordering | GET /v1/sites/{siteId}/firewall/policies/ordering | --from-zone --to-zone | Policy ordering between two zones |
acl-rules | GET /v1/sites/{siteId}/acl-rules | — | ACL rules |
acl-rule | GET /v1/sites/{siteId}/acl-rules/{id} | --id | ACL rule details |
acl-ordering | GET /v1/sites/{siteId}/acl-rules/ordering | — | ACL rule ordering |
dns-policies | GET /v1/sites/{siteId}/dns/policies | — | DNS policies |
dns-policy | GET /v1/sites/{siteId}/dns/policies/{id} | --id | DNS policy details |
traffic-lists | GET /v1/sites/{siteId}/traffic-matching-lists | — | Traffic matching lists |
traffic-list | GET /v1/sites/{siteId}/traffic-matching-lists/{id} | --id | Traffic matching list details |
vouchers | GET /v1/sites/{siteId}/hotspot/vouchers | — | Hotspot vouchers |
voucher | GET /v1/sites/{siteId}/hotspot/vouchers/{id} | --id | Voucher details |
wans | GET /v1/sites/{siteId}/wans | — | WAN interfaces overview |
vpn-tunnels | GET /v1/sites/{siteId}/vpn/site-to-site-tunnels | — | Site-to-site VPN tunnels |
vpn-servers | GET /v1/sites/{siteId}/vpn/servers | — | VPN server configurations |
radius | GET /v1/sites/{siteId}/radius/profiles | — | RADIUS profiles |
device-tags | GET /v1/sites/{siteId}/device-tags | — | Device tags |
dpi-categories | GET /v1/dpi/categories | — | DPI application categories |
dpi-applications | GET /v1/dpi/applications | — | DPI applications |
countries | GET /v1/countries | — | Countries list (for geo-IP rules) |
Examples
# List all sites and pick one to work with
python3 {baseDir}/scripts/unifi.py library
# firewall-ordering: get zone IDs first, then query ordering between two of them
# --from-zone and --to-zone must be real UUIDs from the firewall-zones output
python3 {baseDir}/scripts/unifi.py firewall-zones --site hq
python3 {baseDir}/scripts/unifi.py firewall-ordering --site hq --from-zone <zoneId> --to-zone <zoneId>
# network-refs: get network list first, then query references for a specific network
python3 {baseDir}/scripts/unifi.py networks --site hq
python3 {baseDir}/scripts/unifi.py network-refs --site hq --id <networkId>
# sdwan-config / sdwan-status: list configs first to get an ID
python3 {baseDir}/scripts/unifi.py sdwan
python3 {baseDir}/scripts/unifi.py sdwan-config --id <configId>
python3 {baseDir}/scripts/unifi.py sdwan-status --id <configId>
Site library
On every invocation the skill builds a site library by joining:
GET /v1/hosts— host names (user-set), hardware model, connection state,apiIntegrationflagGET /v1/sites—siteIdperhostId
Labels come directly from the name the user set in the UniFi UI — e.g. "HQ" → hq, "Branch Office" → branch-office, "Remote Site" → remote-site. The library is cached in ~/.unifi-skill.json for 15 minutes to avoid redundant API calls.
Hosts without Network API support (e.g. a NAS device with apiIntegration: false) are included in the library but will return a clear error if targeted with NET subcommands.
Run library to see the current library including state, hardware, and API capability of each host.
Site selection
All NET subcommands accept --site <hint>. The hint is matched against label, name, hardware shortname, hardware name, timezone, and IP — partial matches work.
| User says | Use |
|---|---|
| "the main office network" | --site hq |
| "remote site firewall" | --site remote-site |
| "the branch office" | --site branch-office |
| "the Dream Machine Pro" | --site udmpro |
| "the warehouse AP" | --site warehouse |
If --site is omitted the first entry in the library is used. If the hint is ambiguous the skill lists the matching labels and asks for a more specific hint.
Always specify --site when the user mentions a location or device. When the user says "my network" without specifying, run library first to show what sites are available and ask which one they mean.
How to give advice
Devices (devices, device)
status != "online"→ offline or disconnected — surface to userfirmwareStatus: "updateAvailable"→ firmware update pendingdevice-stats→ CPU/memory/uptime signals for performance issues
Clients (clients, client)
- High noise or weak signal → coverage gap, suggest AP placement review
- Unexpected clients on sensitive VLANs → flag for review
Firewall (firewall-policies, firewall-zones, acl-rules)
- Policies allowing all traffic between sensitive zones → flag as overly broad
- Cross-zone allow rules → confirm intentional with user
- Check
firewall-ordering— rules are evaluated in order; misplaced rules cause unexpected behaviour
DNS (dns-policies)
- Custom DNS policies can bypass filtering — flag any unexpected overrides
VPN (vpn-tunnels, vpn-servers)
- Tunnel state down → connectivity issue to surface
- Verify expected peers are configured
ISP metrics (isp-metrics)
- Packet loss > 1% or latency spikes → WAN quality issue, advise checking with ISP
Notes
network-refsrequires--id(a network ID). Only networks with active references (devices, clients, or WiFi assigned to them) return data — unused networks return a handled error:"Network '...' has no active references". Runnetworksfirst to list all networks, then pass the ID of one that carries traffic.firewall-orderingrequires both--from-zoneand--to-zone. Runfirewall-zonesfirst to list zone IDs. The API returns the ordered policy IDs for traffic flowing from the source zone to the destination zone.sdwan-configandsdwan-statusrequire--id. Runsdwanfirst to list configs and get an ID. These return empty on accounts without SD-WAN configured.
Source & contributing
Source code, issue tracker, and contributions: github.com/arseni-mik/open_claw-unifi-skill
Constraints
- All operations are GET-only. Never suggest using this skill to make changes.
- Guide the user to make changes in the UniFi dashboard or mobile app.
- Do not expose raw API keys in responses.