omada-controller

用途

omada-controller 技能用于通过 TP-Link Omada SDN 控制器的 Open API（OpenAPI 3.0.1）与控制器交互，适合在需要查询或管理 Omada 网络设备、客户端、站点、接入点、交换机、网关等对象时使用。

兼容性

Open API 在 Omada SDN Controller v5.9 及更高版本中可用，包括软件控制器（Software Controller）和云控制器（Cloud-Based Controller）。更早版本仅有使用基于 cookie 会话认证的未公开内部 API，本技能不覆盖该旧版 API。Open API 功能必须由管理员显式启用后才能使用。

环境准备

在发起任何 API 调用前，需要三个环境变量。若用户未提供或不存在 .env 文件，可按以下步骤引导配置：

确定控制器 URL：向用户询问 Omada 控制器地址，软件控制器通常为 https://<host>:8043，安装时若自定义端口则端口可能不同。
创建 API 凭据：登录 Omada 控制器 Web UI，进入 Global View > Settings > Platform Integration > Open API，点击 Add New App，类型设为 Client（不是 Gateway），复制生成的 Client ID 和 Client Secret。
创建 .env 文件：在项目根目录创建 .env 文件，内容如下：

OMADA_URL=https://omada.example.com:8043 OMADA_CLIENT=your-client-id OMADA_SECRET=your-client-secret

切勿将 .env 提交到 git，确保 .gitignore 中包含它。

加载变量后再发起请求：

export $(grep -v '^#' .env | xargs)

不要使用 source .env —— 变量不会传播到子 shell 或 curl。

认证失败的常见原因：控制器未启用 Open API 功能；客户端应用类型设为 Gateway 而非 Client；控制器 URL 错误或缺少端口；在 UI 中轮换了客户端密钥但未更新 .env。

定位包装脚本

API 包装脚本位于本技能目录下的 scripts/omada-api.sh。会话中首次使用时，用 Glob 搜索 **/omada-controller/scripts/omada-api.sh 找到脚本路径，后续调用均使用该绝对路径。例如技能安装在 .claude/skills/omada-controller/，脚本路径为 .claude/skills/omada-controller/scripts/omada-api.sh。

发起 API 调用

所有 Omada API 调用都应使用包装脚本，它自动处理环境变量加载、认证和 URL 构造。

反模式：除 bash <script> ... 之外的任何命令都会触发额外权限提示。切勿用其他命令管道、串联或后处理脚本输出。过滤请使用 --jq FILTER，其余内容自行阅读 JSON 输出。切勿使用 curl、前置赋值或 shell 变量。常见反模式包括：bash <script> ... | jq ...（应改用 --jq FILTER）；bash <script> ... | python3 -c "..."（应改用 --jq 或自行阅读输出）；cat saved-response.txt | python3 -c "..."（应自行阅读 JSON，不要 shell 调用）；curl -sk "${OMADA_URL}/api/info"（应使用脚本而非 curl）；SITE="123" && bash <script> ...（应直接在路径中内联该值）；SITE="123"; for mac in ...（不要使用 shell 变量或循环）。

会话中首次使用时，先不带参数运行健康检查，验证连通性，并让用户一次性批准脚本以便后续所有调用：

bash <script>

随后发起 API 调用：

bash <script> <METHOD> <PATH> [JSON_BODY] [--raw] [--jq FILTER]

路径相对于 /openapi/v1/{omadacId}，无需构造完整 URL 或管理令牌。

示例：

列出站点

bash <script> GET "/sites?page=1&pageSize=100"

列出站点下的设备

bash <script> GET "/sites/{siteId}/devices?page=1&pageSize=100"

重启设备

bash <script> POST /sites/{siteId}/cmd/devices/reboot '{"deviceMacs":["AA-BB-CC-DD-EE-FF"]}'

v2 端点 —— 路径加 /v2 前缀

bash <script> GET /v2/sites/{siteId}/setting/firewall/rules

获取 OpenAPI 规范用于端点发现

bash <script> GET /v3/api-docs --raw

按关键词过滤 API 路径（使用 --jq，切勿管道）

bash <script> GET /v3/api-docs --raw --jq '[.paths | keys[] | select(test("port"; "i"))]'

从分页响应中提取 data 数组

bash <script> GET "/sites/{siteId}/clients?page=1&pageSize=100" --jq '.result.data'

路径路由

脚本自动路由路径：

/sites/... → /openapi/v1/{omadacId}/sites/... /v2/sites/... → /openapi/v2/{omadacId}/sites/... /v3/api-docs → {OMADA_URL}/v3/api-docs（无认证前缀）

API 发现

控制器托管自己的完整 OpenAPI 3.0.1 规范（约 1507 个端点）。可用它在运行时发现任意端点，而非硬编码路径。

Swagger UI（浏览器）：{OMADA_URL}/swagger-ui/index.html —— 无需认证

OpenAPI 规范（JSON）：

bash <script> GET /v3/api-docs --raw --jq '.paths | keys[]'

常见模式

站点 ID：大多数端点以站点为作用域。先获取站点 ID：

bash <script> GET "/sites?page=1&pageSize=100"

随后在后续路径中使用：/sites/{siteId}/devices、/sites/{siteId}/clients 等。

分页：分页端点接受 page 和 pageSize 查询参数，返回：

{ "errorCode": 0, "result": { "totalRows": 7, "currentPage": 1, "currentSize": 100, "data": [...] } }

API 版本：部分端点使用 /v2/ 而非默认的 /v1/。swagger 规范包含两者 —— 需要时在路径前加 /v2。

认证细节

包装脚本自动处理认证，仅供参考：

控制器 ID：从 GET {OMADA_URL}/api/info 获取（不在 OpenAPI 规范内）
令牌：OAuth2 客户端凭据，通过 POST {OMADA_URL}/openapi/authorize/token?grant_type=client_credentials 获取，JSON body 中包含 omadacId、client_id、client_secret（grant_type 是查询参数，不在 body 中）
请求头格式：Authorization: AccessToken=<token>（不是 Bearer）
有效期：令牌有效 2 小时（7200 秒）—— 脚本每次调用都会重新认证

注意事项

引号：包含 & 的路径务必加引号（如 "/sites?page=1&pageSize=100"）。未加引号的 & 是 shell 后台操作符。
TLS：控制器通常使用自签名证书，始终使用 curl -k。
MAC 格式：API 使用 AA-BB-CC-DD-EE-FF（大写、短横线）。
错误处理：始终检查响应中的 errorCode。0 = 成功，负数 = 错误。
令牌请求头：Authorization: AccessToken=<token>，不是 Bearer <token>。

参考资源

scripts/omada-api.sh —— API 包装（处理环境、认证和请求）
references/api-categories.md —— API 端点类别与数量
references/external-resources.md —— 文档、示例和集成链接

技能介绍

用途

兼容性