功能描述

Use when asked to manage UniFi network - list/restart/upgrade devices, block/unblock clients, manage WiFi networks, control PoE ports, manage traffic rules, create guest vouchers, or any UniFi controller task. Works with UDM Pro/SE, Dream Machine, Cloud Key Gen2+, or self-hosted controllers.

使用说明 (SKILL.md)

ez-unifi

Name: EZ Unifi
Author: araa47

Agent-friendly UniFi Network tools powered by the aiounifi library. Supports UDM Pro/SE, Dream Machine, Cloud Key Gen2+, and self-hosted controllers.

Run all commands with: uv run scripts/unifi.py \x3Ccommand> [args]

Setup

Step 1: Ask user to create a dedicated local admin account

To manage your UniFi network, I need API access. Please create a dedicated local admin account:

Open your UniFi controller (e.g., https://192.168.1.1)

Go to Settings → System → Admins & Users

Click Add Admin

Enter a username (e.g., agent-api)

Enter an email and password

Important: Disable "Remote Access" - local-only avoids MFA issues

Set Role to Super Admin or Site Admin

Click Add

Then provide:

Controller IP (e.g., 192.168.1.1)

Username

Password

Is it a UDM Pro/SE/Dream Machine? (yes/no)

Step 2: Save credentials to .env

UNIFI_HOST=https://192.168.1.1
UNIFI_USERNAME=agent-api
UNIFI_PASSWORD=the_password
UNIFI_SITE=default
UNIFI_IS_UDM=true

Set UNIFI_IS_UDM=false for Cloud Key Gen1 or self-hosted controllers.

System & Sites

unifi.py sites                     # List all sites
unifi.py sysinfo                   # System information
unifi.py health                    # Site health status (WAN, WLAN, LAN)

Devices (APs, Switches, Gateways)

unifi.py devices                   # List all devices
unifi.py device MAC                # Device details
unifi.py restart MAC               # Restart device
unifi.py restart MAC --hard        # Hard restart (cycles PoE on switches)
unifi.py upgrade MAC               # Upgrade device firmware
unifi.py locate MAC                # Blink LED to locate
unifi.py unlocate MAC              # Stop LED blinking
unifi.py led MAC on|off|default    # Set LED status
unifi.py led MAC on --color=#FF0000 --brightness=50  # With color/brightness

Switch Ports

unifi.py ports                     # List all switch ports
unifi.py port MAC PORT_IDX         # Port details
unifi.py port-enable MAC PORT_IDX  # Enable switch port
unifi.py port-disable MAC PORT_IDX # Disable switch port
unifi.py poe MAC PORT_IDX MODE     # Set PoE mode (auto|off|passthrough|24v)
unifi.py power-cycle MAC PORT_IDX  # Power cycle a PoE port

Smart Power (PDU/Outlets)

unifi.py outlets                   # List all outlets
unifi.py outlet MAC IDX on|off     # Control outlet relay
unifi.py outlet-cycle MAC IDX on|off  # Enable/disable auto-cycle on internet down

Clients

unifi.py clients                   # List active clients
unifi.py clients-all               # List all clients (including offline/known)
unifi.py client MAC                # Client details
unifi.py block MAC                 # Block client from network
unifi.py unblock MAC               # Unblock client
unifi.py reconnect MAC             # Kick/reconnect client
unifi.py forget MAC [MAC2...]      # Forget client(s) permanently

WiFi Networks

unifi.py wlans                     # List wireless networks
unifi.py wlan ID                   # WLAN details
unifi.py wlan-enable ID            # Enable WLAN
unifi.py wlan-disable ID           # Disable WLAN
unifi.py wlan-password ID NEWPASS  # Change WLAN password
unifi.py wlan-qr ID                # Generate WiFi QR code (PNG file)
unifi.py wlan-qr ID -o myqr.png    # Custom output filename

Port Forwarding

unifi.py port-forwards             # List port forwarding rules
unifi.py port-forward ID           # Port forward details

Traffic Rules

unifi.py traffic-rules             # List traffic rules
unifi.py traffic-rule ID           # Traffic rule details
unifi.py traffic-rule-enable ID    # Enable traffic rule
unifi.py traffic-rule-disable ID   # Disable traffic rule
unifi.py traffic-rule-toggle ID on|off  # Toggle traffic rule state

Traffic Routes

unifi.py traffic-routes            # List traffic routes
unifi.py traffic-route ID          # Traffic route details
unifi.py traffic-route-enable ID   # Enable traffic route
unifi.py traffic-route-disable ID  # Disable traffic route

Firewall

unifi.py firewall-policies         # List firewall policies
unifi.py firewall-policy ID        # Firewall policy details
unifi.py firewall-zones            # List firewall zones
unifi.py firewall-zone ID          # Firewall zone details

DPI (Deep Packet Inspection)

unifi.py dpi-apps                  # List DPI restriction apps
unifi.py dpi-app ID                # DPI app details
unifi.py dpi-app-enable ID         # Enable DPI app restriction
unifi.py dpi-app-disable ID        # Disable DPI app restriction
unifi.py dpi-groups                # List DPI restriction groups
unifi.py dpi-group ID              # DPI group details

Hotspot Vouchers

unifi.py vouchers                  # List vouchers
unifi.py voucher-create --duration=60 --quota=1 --note="Guest"
unifi.py voucher-create --duration=1440 --quota=5 --rate-up=5000 --rate-down=10000
unifi.py voucher-delete ID         # Delete voucher

Voucher options:

--duration - Duration in minutes (default: 60)
--quota - Number of uses (default: 1)
--usage-quota - Usage quota in MB
--rate-up - Upload rate limit in Kbps
--rate-down - Download rate limit in Kbps
--note - Note/description

Events

unifi.py events                    # Stream events in real-time (Ctrl+C to stop)

Raw API Access

unifi.py raw GET /stat/health      # Raw GET request
unifi.py raw POST /cmd/devmgr '{"cmd":"restart","mac":"aa:bb:cc:dd:ee:ff"}'
unifi.py raw PUT /rest/wlanconf/ID '{"enabled":false}'

Output Options

Add --json flag to any list command for JSON output:

unifi.py devices --json            # JSON output
unifi.py clients --json

Examples

# Check network health
uv run scripts/unifi.py health

# List all connected clients
uv run scripts/unifi.py clients

# Block a device
uv run scripts/unifi.py block "aa:bb:cc:dd:ee:ff"

# Restart an access point
uv run scripts/unifi.py restart "11:22:33:44:55:66"

# Disable guest WiFi
uv run scripts/unifi.py wlan-disable "5f8b3d2e1a4c7b9e0d6f8a2c"

# Upgrade device firmware
uv run scripts/unifi.py upgrade "11:22:33:44:55:66"

# Power cycle a PoE port (useful for rebooting PoE devices)
uv run scripts/unifi.py power-cycle "switch_mac" 5

# Create a guest voucher (24 hours, single use)
uv run scripts/unifi.py voucher-create --duration=1440 --quota=1 --note="Guest access"

# Generate WiFi QR code for easy connection
uv run scripts/unifi.py wlan-qr "wlan_id" -o guest_wifi.png

# Control traffic rule
uv run scripts/unifi.py traffic-rule-disable "rule_id"

Finding IDs

WLAN IDs: Run wlans and look for the ID column
Device MACs: Run devices and look for the MAC column
Client MACs: Run clients or clients-all and look for the MAC column
Traffic Rule IDs: Run traffic-rules and look for the ID column
Voucher IDs: Run vouchers and look for the ID column

Notes

MAC addresses can be any format (with colons, dashes, or none)
All output is JSON for easy parsing
Using a dedicated local account avoids MFA issues with cloud-linked accounts
If you get rate limited (429 error), wait a few minutes before retrying

安全使用建议

This skill looks like a real UniFi management tool, but there are a few red flags to consider before installing: (1) the registry metadata does not declare the UNIFI_* environment variables that the script and SKILL.md require — confirm where credentials will be stored and why the metadata omits them; (2) the skill asks you to create/use a Super Admin account and to store the password in a plaintext .env file — prefer a least-privilege account if possible, use a dedicated account, and avoid long-term plaintext storage; (3) the code disables SSL verification (accepts self-signed certs) which weakens TLS checks — consider securing your controller certificate instead of disabling verification; (4) because the agent can invoke this skill autonomously and it has network-admin credentials, limit who/what can call it and consider interactive-only invocation if you want manual approval for destructive actions; (5) review the full script yourself (or have a trusted admin do so) for any hidden network calls or telemetry before providing credentials, and rotate the account password after initial setup. If you can't inspect the code or confirm the author, treat the skill as higher risk and avoid providing high-privilege credentials.

功能分析

Type: OpenClaw Skill Name: ez-unifi Version: 1.0.1 The skill is classified as suspicious due to two main risky capabilities. First, the `scripts/unifi.py` script disables SSL certificate verification (`ssl_context=False`) when connecting to the UniFi controller, which makes the connection vulnerable to Man-in-the-Middle attacks. Second, the script exposes a 'raw API access' command (`unifi.py raw`) allowing arbitrary HTTP methods and paths to be sent to the controller, which grants very broad permissions and significantly increases the attack surface if the agent were to be compromised by a prompt injection, enabling actions beyond the explicitly defined commands.

能力评估

ℹ Purpose & Capability

The skill's functionality (UniFi management) matches the name and description — the code uses aiounifi and exposes appropriate controller operations. However, the registry declares no required environment variables or primary credential, while the SKILL.md and script clearly require UNIFI_HOST, UNIFI_USERNAME, and UNIFI_PASSWORD (and optionally UNIFI_SITE, UNIFI_IS_UDM). The metadata omission is an incoherence that should be corrected.

ℹ Instruction Scope

The SKILL.md stays within the stated purpose and gives explicit CLI usage. It instructs the user to create a dedicated local admin account and to save controller credentials to a .env file. This is expected for controller management, but it also requests a Super Admin (or Site Admin) account — a high privilege level — and directs storing plaintext credentials locally, which broadens the risk profile.

✓ Install Mechanism

There is no install spec (instruction-only skill) and no external downloads; the script lists Python dependencies in comments but does not attempt remote installs. This is lower risk from an installation perspective, but users must manually install/verify the declared dependencies.

⚠ Credentials

The skill requires direct controller credentials (UNIFI_HOST, UNIFI_USERNAME, UNIFI_PASSWORD) but the registry metadata does not declare them. Asking for Super Admin credentials is high privilege; while many actions require admin rights, the request should be explicit in metadata. The SKILL.md recommends saving credentials to an unencrypted .env file, which is insecure. The code also disables SSL verification (ssl_context=False) to accept self-signed certs, reducing TLS protection.

ℹ Persistence & Privilege

The skill is not always-enabled and does not request persistent platform privileges. However, because it can be invoked autonomously (default) and would hold network-admin credentials, an agent could make changes without interactive confirmation; users should be comfortable with that level of autonomous access before enabling the skill.

版本历史

v1.0.1

- Adds documentation for new commands: enable/disable switch ports, per-item details for port forwards, traffic routes, firewall policies/zones, DPI apps/groups. - Documents new commands for toggling traffic rule states and changing WLAN passwords. - Expands command usage examples and explanations for greater coverage and clarity.

v1.0.0

ez-unifi 1.0.0 – Initial Release - Provides comprehensive agent-friendly UniFi network management via the `aiounifi` library. - Supports UDM Pro/SE, Dream Machine, Cloud Key Gen2+, and self-hosted controllers. - Features extensive command set: manage devices, clients, WiFi, PoE ports, traffic rules, port forwarding, vouchers, and more. - Simple setup with local admin account creation and environment variable configuration. - Offers raw UniFi API access and flexible JSON output for all list commands. - Designed for easy integration and automation of UniFi controller tasks.

元数据

Slug ez-unifi

版本 1.0.1

许可证 —

累计安装 2

当前安装数 2

历史版本数 2

常见问题

EZ Unifi 是什么？

Use when asked to manage UniFi network - list/restart/upgrade devices, block/unblock clients, manage WiFi networks, control PoE ports, manage traffic rules, create guest vouchers, or any UniFi controller task. Works with UDM Pro/SE, Dream Machine, Cloud Key Gen2+, or self-hosted controllers. 它是一个面向 Claude Code / OpenClaw 的 AI Agent Skill 插件，目前累计下载 2096 次。

如何安装 EZ Unifi？

在 OpenClaw 或 Claude Code 对话框中运行命令「/install ez-unifi」即可一键安装，无需额外配置。

EZ Unifi 是免费的吗？

是的，EZ Unifi 完全免费（开源免费），可自由下载、安装和使用。

EZ Unifi 支持哪些平台？

EZ Unifi 跨平台运行，可在任意部署了 OpenClaw / Claude Code 的环境中使用（cross-platform）。

谁开发了 EZ Unifi？

由 araa47（@araa47）开发并维护，当前版本 v1.0.1。

EZ Unifi