omada-controller

Omada SDN Controller API

通过 Open API（OpenAPI 3.0.1）管理 TP-Link Omada SDN Controller。

兼容性

Open API 适用于 Omada SDN Controller v5.9 及更高版本（软件控制器和云端控制器均支持）。较早版本仅提供未公开文档的内部 API，该 API 使用基于 Cookie 的会话身份验证——本技能不涵盖此旧版 API。

使用前，管理员必须显式启用 Open API 功能。

环境设置

进行任何 API 调用之前，需要设置三个环境变量。如果用户尚未提供这些变量，或者 .env 文件不存在，请引导用户完成设置：

1. 查找控制器 URL——询问用户 Omada Controller 的地址。软件控制器的地址通常为 https://<host>:8043。如果安装时自定义了端口，端口号可能不同。

2. 创建 API 凭据——引导用户：

   • 登录 Omada Controller Web 界面
   • 导航至 Global View > Settings > Platform Integration > Open API
   • 点击 Add New App
   • 将类型设为 Client（而不是 Gateway）
   • 复制生成的 Client ID 和 Client Secret

3. 创建 .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 错误或缺少端口号
• 在界面中轮换了客户端密钥，但未更新 .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 或管理令牌。

示例

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

# List devices at a site
bash <script> GET "/sites/{siteId}/devices?page=1&pageSize=100"

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

# v2 endpoints — prefix path with /v2
bash <script> GET /v2/sites/{siteId}/setting/firewall/rules

# Fetch the OpenAPI spec for endpoint discovery
bash <script> GET /v3/api-docs --raw

# Filter API paths by keyword (use --jq, NEVER pipe)
bash <script> GET /v3/api-docs --raw --jq '[.paths | keys[] | select(test("port"; "i"))]'

# Extract just the data array from a paginated response
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（无身份验证前缀）

建议的权限设置

建议用户在 Claude Code 设置中添加以下内容，以免每次运行脚本都收到提示：

Bash(bash *omada-api.sh *)

API 发现

控制器托管了完整的 OpenAPI 3.0.1 规范（约 1,507 个端点）。使用它在运行时发现任意端点，而不要将路径硬编码。

• 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。

身份验证详情

封装脚本会自动处理身份验证，以下信息供参考：

1. 控制器 ID：通过 GET {OMADA_URL}/api/info 获取（不在 OpenAPI 规范中）
2. 令牌：使用 POST {OMADA_URL}/openapi/authorize/token?grant_type=client_credentials，通过 OAuth2 客户端凭据获取；在 JSON 请求体中传入 omadacId、client_id、client_secret（grant_type 是查询参数，不是请求体参数）
3. 请求头格式：Authorization: AccessToken=<token>（不是 Bearer）
4. 有效期：令牌有效期为 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 — 文档、示例和集成的链接