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.

How to call the script

python3 {baseDir}/scripts/unifi.py \x3Csubcommand> [--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

Network Integration (NET) — proxied via api.ui.com, site resolved automatically

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 \x3CzoneId> --to-zone \x3CzoneId>

# 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 \x3CnetworkId>

# 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 \x3CconfigId>
python3 {baseDir}/scripts/unifi.py sdwan-status --id \x3CconfigId>

Site library

On every invocation the skill builds a site library by joining:

• GET /v1/hosts — host names (user-set), hardware model, connection state, apiIntegration flag
• GET /v1/sites — siteId per hostId

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 \x3Chint>. The hint is matched against label, name, hardware shortname, hardware name, timezone, and IP — partial matches work.

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 user
• firmwareStatus: "updateAvailable" → firmware update pending
• device-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-refs requires --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". Run networks first to list all networks, then pass the ID of one that carries traffic.
• firewall-ordering requires both --from-zone and --to-zone. Run firewall-zones first to list zone IDs. The API returns the ordered policy IDs for traffic flowing from the source zone to the destination zone.
• sdwan-config and sdwan-status require --id. Run sdwan first 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.