什么是 ez-unifi？

ez-unifi 是一个技术桥梁，使 AI 代理能够直接与 UniFi 网络控制器交互。通过利用 aiounifi 库，该工具将复杂的网络管理任务转化为简单的、代理可执行的命令。它支持广泛的硬件，包括 UDM Pro、UDM SE、Dream Machine 和自托管控制器，是 Openclaw Skills 库中不可或缺的补充。

此技能专为希望自动化网络基础设施的开发人员和家庭实验室爱好者设计。它允许您的 AI 代理监控系统健康状况、管理 PoE 交换机端口、配置访客 WiFi 并应用防火墙规则，而无需手动登录 UniFi Web 界面。通过提供结构化的 JSON 输出，它确保您的自动化工作流程保持可靠且由数据驱动。

下载入口:https://github.com/openclaw/skills/tree/main/skills/araa47/ez-unifi

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

ez-unifi 应用场景

• 实时监控全站网络健康状况和系统信息。
• 自动化接入点和交换机的固件更新及重启周期。
• 通过阻止未经授权的设备或为访客生成热点优惠券来管理客户端访问。
• 通过 PoE 端口电源循环和智能插座管理控制物理硬件。
• 调整 WiFi 配置，例如轮换密码或生成二维码以便快速接入。
• 通过自然语言指令实施流量管理策略和防火墙规则。

1. AI 代理从用户处接收与网络相关的提示，并识别适当的 ez-unifi 命令。
2. 代理使用 uv 运行器执行 unifi.py 脚本，并传递必要的参数。
3. 脚本使用环境变量中定义的安全性局部管理员凭据向 UniFi 控制器进行身份验证。
4. 通过 aiounifi API 封装器将命令发送到控制器，以执行设备重启或配置更改等操作。
5. 控制器返回响应，脚本将其格式化为整洁的 JSON 以供代理理解。
6. 代理根据 API 响应向用户提供易于阅读的确认或数据摘要。

ez-unifi 配置指南

要在 Openclaw Skills 环境中部署此工具，请遵循以下安装步骤：

1. 创建本地管理员帐户：

   • 登录您的 UniFi 控制器，前往 设置 → 系统 → 管理员与用户。
   • 添加一个新的管理员（例如 agent-api），并 禁用远程访问，以确保在没有多因素验证 (MFA) 的情况下实现兼容性。

2. 配置环境变量： 创建一个 .env 文件并填入您的控制器详细信息：

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

3. 运行测试命令： 通过列出您的网络设备来验证连接：

   uv run scripts/unifi.py devices
   

ez-unifi 数据架构与分类体系

该技能与 UniFi 生态系统中的多个核心数据实体交互。所有列表命令均可输出 JSON，以便集成到更大的自动化流水线中。

name: ez-unifi
description: 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.
metadata: {"openclaw":{"emoji":"??"}}

ez-unifi

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 [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:

1. Open your UniFi controller (e.g., https://192.168.1.1)
2. Go to Settings → System → Admins & Users
3. Click Add Admin
4. Enter a username (e.g., agent-api)
5. Enter an email and password
6. Important: Disable "Remote Access" - local-only avoids MFA issues
7. Set Role to Super Admin or Site Admin
8. 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