Omada Viewer
Read-only diagnostics for TP-Link Omada SDN controllers via the Open API.
What it does
Use this skill to inspect:
- - Devices
- Clients
- VLANs / LAN networks
- WAN status
- Router ports
- Switch ports
- DHCP ranges
- Port forwards
- General controller health
What it does NOT do
- - Does not make configuration changes
- Does not create, edit, or delete controller settings
- Does not require Admin role for normal use
Requirements
This skill does require:
- - A reachable Omada controller over HTTPS
- A user-created Open API application in Omada
- User-provided credentials for that API app
Recommended role:
Required configuration:
- - INLINECODE0
- INLINECODE1
- INLINECODE2
Optional configuration:
- - INLINECODE3
- INLINECODE4
- INLINECODE5
Quick Setup
- 1. In Omada, go to:
-
Settings > Platform Integration > Open API
- 2. Create an application in:
-
Client mode
- 3. Prefer this permission level:
-
Viewer
- 4. Store credentials locally, not in chat
Common Commands
CODEBLOCK0
Authentication
Use client credentials mode:
CODEBLOCK1
Successful responses return:
- - INLINECODE6
- INLINECODE7
- INLINECODE8
Use the token like this:
CODEBLOCK2
Important notes:
- - Send JSON as UTF-8 without BOM
- Some local controllers allow
omadacId discovery from INLINECODE10
Core Read Endpoints
All site-scoped paths below are relative to:
CODEBLOCK3
Discovery
- - INLINECODE11
- INLINECODE12
Devices and Clients
- - INLINECODE13
- INLINECODE14
- INLINECODE15
- INLINECODE16
LAN / VLAN / DHCP
- - INLINECODE17
- INLINECODE18
- INLINECODE19
Typical LAN network responses may include:
- - VLAN ID
- Gateway subnet
- DHCP range
- DNS settings
- Lease time
Port Forwards / NAT / Firewall
- - INLINECODE20
- INLINECODE21
- INLINECODE22
- INLINECODE23
Gateway / WAN / Router Ports
- - INLINECODE24
- INLINECODE25
- INLINECODE26
- INLINECODE27
- INLINECODE28
- INLINECODE29
- INLINECODE30
- INLINECODE31
Switches / APs
- - INLINECODE32
- INLINECODE33
- INLINECODE34
- INLINECODE35
- INLINECODE36
- INLINECODE37
- INLINECODE38
Script Commands
Use scripts/omada_query.py for quick diagnostics.
Supported commands:
CODEBLOCK4
Included References
- -
references/api-endpoints.md — compact endpoint reference - INLINECODE41 — practical starting endpoints
- INLINECODE42 — categorized endpoint catalog
- INLINECODE43 — regenerate endpoint catalog from an OpenAPI export
Security Notes
- - Prefer Viewer role for normal use
- Never paste secrets into chat
- Keep read-only diagnostics separate from any future admin/write skill
- If you later publish a write-capable version, use a separate Admin-scoped API app
Troubleshooting
- - 401 / auth failures: verify Client mode, credentials, and INLINECODE44
- Invalid credential errors: confirm exact
client_id, client_secret, and INLINECODE47 - SSL errors: local controllers with self-signed certs may require SSL verification disabled
- Missing endpoints: API coverage varies by controller version, model, and enabled features
- Unexpected JSON/auth issues: ensure request body is UTF-8 without BOM
Omada Viewer
通过 Open API 对 TP-Link Omada SDN 控制器进行只读诊断。
功能说明
使用此技能可检查：
- - 设备
- 客户端
- VLAN / LAN 网络
- WAN 状态
- 路由器端口
- 交换机端口
- DHCP 范围
- 端口转发
- 控制器常规健康状态
不支持的操
- - 不进行配置更改
- 不创建、编辑或删除控制器设置
- 正常使用不需要管理员角色
前提条件
此技能确实需要：
- - 可通过 HTTPS 访问的 Omada 控制器
- 在 Omada 中用户创建的 Open API 应用程序
- 用户提供的该 API 应用的凭据
推荐角色：
必需配置：
- - OMADAURL
- OMADACLIENTID
- OMADACLIENT_SECRET
可选配置：
- - OMADAOMADACID
- OMADASITE
- OMADAVERIFY_SSL
快速设置
- 1. 在 Omada 中，进入：
-
设置 > 平台集成 > Open API
- 2. 在以下位置创建应用程序：
-
客户端模式
- 3. 优先选择此权限级别：
-
查看者
- 4. 将凭据存储在本地，而非聊天中
常用命令
bash
python scripts/omada_query.py summary
python scripts/omada_query.py clients
python scripts/omada_query.py devices
python scripts/omada_query.py vlans
python scripts/omada_query.py port-forwards
python scripts/omada_query.py wan-status
python scripts/omada_query.py router-summary
身份验证
使用客户端凭据模式：
http
POST {baseurl}/openapi/authorize/token?granttype=client_credentials
Content-Type: application/json
{
omadacId: ,
clientid: id>,
clientsecret: secret>
}
成功响应返回：
- - accessToken
- refreshToken
- expiresIn
按如下方式使用令牌：
http
Authorization: AccessToken=
重要提示：
- - 以 UTF-8 无 BOM 格式发送 JSON
- 部分本地控制器允许通过 GET /api/info 发现 omadacId
核心只读端点
以下所有站点范围路径均相对于：
text
/openapi/v1/{omadacId}/sites/{siteId}
发现
- - GET /api/info
- GET /openapi/v1/{omadacId}/sites?page=1&pageSize=100
设备和客户端
- - GET /devices?page=1&pageSize=200
- GET /devices/{deviceMac}
- GET /clients?page=1&pageSize=200
- GET /clients/{clientMac}
LAN / VLAN / DHCP
- - GET /lan-networks?page=1&pageSize=50
- GET /lan-networks/{networkId}
- GET /networks/vlans
典型的 LAN 网络响应可能包含：
- - VLAN ID
- 网关子网
- DHCP 范围
- DNS 设置
- 租约时间
端口转发 / NAT / 防火墙
- - GET /nat/port-forwardings?page=1&pageSize=50
- GET /firewall
- GET /firewall/timeout/default
- GET /insight/port-forwarding/{type}
网关 / WAN / 路由器端口
- - GET /gateways/{gatewayMac}
- GET /gateways/{gatewayMac}/ports
- GET /gateways/{gatewayMac}/wan-status
- GET /gateways/{gatewayMac}/lan-status
- GET /internet/ports-config
- GET /internet/load-balance
- GET /internet/load-balance/status
- GET /health/gateways/{gatewayMac}/wans/details
交换机 / AP
- - GET /switches/{switchMac}/ports
- GET /port-status-ports
- GET /poe-ports
- GET /aps/{apMac}
- GET /aps/{apMac}/ports
- GET /aps/{apMac}/port-vlans
- GET /aps/{apMac}/vlan
脚本命令
使用 scripts/omada_query.py 进行快速诊断。
支持的命令：
bash
python scripts/omada_query.py sites
python scripts/omada_query.py devices
python scripts/omada_query.py clients
python scripts/omada_query.py vlans
python scripts/omada_query.py dhcp-reservations
python scripts/omada_query.py port-forwards
python scripts/omadaquery.py switch-ports mac>
python scripts/omada_query.py wan-ports
python scripts/omada_query.py wan-status
python scripts/omada_query.py router-ports
python scripts/omada_query.py router-summary
python scripts/omada_query.py summary
附带的参考文件
- - references/api-endpoints.md — 精简端点参考
- references/discovered-endpoints.md — 实用起始端点
- references/all-endpoints.md — 分类端点目录
- scripts/extract_endpoints.py — 从 OpenAPI 导出重新生成端点目录
安全注意事项
- - 正常使用优先选择查看者角色
- 切勿将密钥粘贴到聊天中
- 将只读诊断与任何未来的管理/写入技能分开
- 如果后续发布支持写入的版本，请使用单独的管理员范围 API 应用
故障排除
- - 401 / 身份验证失败：检查客户端模式、凭据和 granttype=clientcredentials
- 凭据无效错误：确认准确的 clientid、clientsecret 和 omadacId
- SSL 错误：使用自签名证书的本地控制器可能需要禁用 SSL 验证
- 缺少端点：API 覆盖范围因控制器版本、型号和启用的功能而异
- 意外的 JSON/身份验证问题：确保请求体为 UTF-8 格式且无 BOM
