名称： ez-unifi
描述： 当需要管理 UniFi 网络时使用——可列出/重启/升级设备、封禁/解封客户端、管理 WiFi 网络、控制 PoE 端口、管理流量规则、创建访客凭证，或执行任何 UniFi 控制器任务。支持 UDM Pro/SE、Dream Machine、Cloud Key Gen2+ 或自托管控制器。
元数据： {"openclaw":{"emoji":"📶"}}

ez-unifi

基于 aiounifi 库开发的智能体友好型 UniFi 网络工具。支持 UDM Pro/SE、Dream Machine、Cloud Key Gen2+ 及自托管控制器。

所有命令运行方式： uv run scripts/unifi.py <命令> [参数]

初始设置

步骤一：请用户创建专用的本地管理员账户

为管理您的 UniFi 网络，我需要 API 访问权限。请创建一个专用的本地管理员账户：

1. 打开 UniFi 控制器（例如 https://192.168.1.1）
2. 进入 设置 → 系统 → 管理员与用户
3. 点击 添加管理员
4. 输入用户名（例如 agent-api）
5. 输入邮箱和密码
6. 重要：禁用“远程访问”——仅限本地访问可避免 MFA 问题
7. 将角色设置为 超级管理员 或 站点管理员
8. 点击 添加

完成后请提供：
- 控制器 IP（例如 192.168.1.1）
- 用户名
- 密码
- 是否为 UDM Pro/SE/Dream Machine？（是/否）

步骤二：将凭据保存至 .env 文件

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

对于 Cloud Key Gen1 或自托管控制器，请设置 UNIFI_IS_UDM=false。

系统与站点

unifi.py sites                     # 列出所有站点
unifi.py sysinfo                   # 系统信息
unifi.py health                    # 站点健康状态（WAN、WLAN、LAN）

设备（AP、交换机、网关）

unifi.py devices                   # 列出所有设备
unifi.py device MAC                # 查看设备详情
unifi.py restart MAC               # 重启设备
unifi.py restart MAC --hard        # 强制重启（对交换机执行 PoE 循环）
unifi.py upgrade MAC               # 升级设备固件
unifi.py locate MAC                # 闪烁 LED 以定位设备
unifi.py unlocate MAC              # 停止 LED 闪烁
unifi.py led MAC on|off|default    # 设置 LED 状态
unifi.py led MAC on --color=#FF0000 --brightness=50  # 自定义颜色/亮度

交换机端口

unifi.py ports                     # 列出所有交换机端口
unifi.py port MAC PORT_IDX         # 查看端口详情
unifi.py port-enable MAC PORT_IDX  # 启用交换机端口
unifi.py port-disable MAC PORT_IDX # 禁用交换机端口
unifi.py poe MAC PORT_IDX MODE     # 设置 PoE 模式（auto|off|passthrough|24v）
unifi.py power-cycle MAC PORT_IDX  # 对 PoE 端口执行电源循环

智能电源（PDU/插座）

unifi.py outlets                   # 列出所有插座
unifi.py outlet MAC IDX on|off     # 控制插座继电器
unifi.py outlet-cycle MAC IDX on|off  # 启用/禁用网络中断时自动循环

客户端

unifi.py clients                   # 列出活跃客户端
unifi.py clients-all               # 列出所有客户端（包括离线/已知设备）
unifi.py client MAC                # 查看客户端详情
unifi.py block MAC                 # 封禁客户端
unifi.py unblock MAC               # 解封客户端
unifi.py reconnect MAC             # 踢出/重连客户端
unifi.py forget MAC [MAC2...]      # 永久移除客户端

WiFi 网络

unifi.py wlans                     # 列出无线网络
unifi.py wlan ID                   # 查看 WLAN 详情
unifi.py wlan-enable ID            # 启用 WLAN
unifi.py wlan-disable ID           # 禁用 WLAN
unifi.py wlan-password ID NEWPASS  # 修改 WLAN 密码
unifi.py wlan-qr ID                # 生成 WiFi 二维码（PNG 文件）
unifi.py wlan-qr ID -o myqr.png    # 自定义输出文件名

端口转发

unifi.py port-forwards             # 列出端口转发规则
unifi.py port-forward ID           # 查看端口转发详情

流量规则

unifi.py traffic-rules             # 列出流量规则
unifi.py traffic-rule ID           # 查看流量规则详情
unifi.py traffic-rule-enable ID    # 启用流量规则
unifi.py traffic-rule-disable ID   # 禁用流量规则
unifi.py traffic-rule-toggle ID on|off  # 切换流量规则状态

流量路由

unifi.py traffic-routes            # 列出流量路由
unifi.py traffic-route ID          # 查看流量路由详情
unifi.py traffic-route-enable ID   # 启用流量路由
unifi.py traffic-route-disable ID  # 禁用流量路由

防火墙

unifi.py firewall-policies         # 列出防火墙策略
unifi.py firewall-policy ID        # 查看防火墙策略详情
unifi.py firewall-zones            # 列出防火墙区域
unifi.py firewall-zone ID          # 查看防火墙区域详情

DPI（深度包检测）

unifi.py dpi-apps                  # 列出 DPI 限制应用
unifi.py dpi-app ID                # 查看 DPI 应用详情
unifi.py dpi-app-enable ID         # 启用 DPI 应用限制
unifi.py dpi-app-disable ID        # 禁用 DPI 应用限制
unifi.py dpi-groups                # 列出 DPI 限制组
unifi.py dpi-group ID              # 查看 DPI 限制组详情

热点访客凭证

unifi.py vouchers                  # 列出访客凭证
unifi.py voucher-create --duration=60 --quota=1 --note="访客"
unifi.py voucher-create --duration=1440 --quota=5 --rate-up=5000 --rate-down=10000
unifi.py voucher-delete ID         # 删除凭证

凭证选项：
- --duration - 有效时长（分钟，默认：60）
- --quota - 使用次数（默认：1）
- --usage-quota - 使用流量配额（MB）
- --rate-up - 上传速率限制（Kbps）
- --rate-down - 下载速率限制（Kbps）
- --note - 备注/描述

事件

unifi.py events                    # 实时流式传输事件（按 Ctrl+C 停止）

原始 API 访问

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

输出选项

在任何列表命令后添加 --json 标志以获取 JSON 输出：

unifi.py devices --json            # JSON 格式输出
unifi.py clients --json

使用示例

# 检查网络健康状态
uv run scripts/unifi.py health

# 列出所有已连接客户端
uv run scripts/unifi.py clients

# 封禁设备
uv run scripts/unifi.py block "aa:bb:cc:dd:ee:ff"

# 重启接入点
uv run scripts/unifi.py restart "11:22:33:44:55:66"

# 禁用访客 WiFi
uv run scripts/unifi.py wlan-disable "5f8b3d2e1a4c7b9e0d6f8a2c"

# 升级设备固件
uv run scripts/unifi.py upgrade "11:22:33:44:55:66"

# 对 PoE 端口执行电源循环（适用于重启 PoE 设备）
uv run scripts/unifi.py power-cycle "switch_mac" 5

# 创建访客凭证（24 小时，单次使用）
uv run scripts/unifi.py voucher-create --duration=1440 --quota=1 --note="访客访问"

# 生成 WiFi 二维码以便快速连接
uv run scripts/unifi.py wlan-qr "wlan_id" -o guest_wifi.png

# 控制流量规则
uv run scripts/unifi.py traffic-rule-disable "rule_id"

如何查找 ID

• WLAN ID：运行 wlans 命令，查看 ID 列
• 设备 MAC：运行 devices 命令，查看 MAC 列
• 客户端 MAC：运行 clients 或 clients-all 命令，查看 MAC 列
• 流量规则 ID：运行 traffic-rules 命令，查看 ID 列
• 凭证 ID：运行 vouchers 命令，查看 ID 列

注意事项

• MAC 地址支持任意格式（带冒号、短横线或无分隔符）
• 所有输出均为 JSON 格式，便于解析
• 使用专用的本地账户可避免云关联账户的 MFA 问题
• 若遇到速率限制（429 错误），请等待几分钟后重试