omada-controller

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Omada SDN Controller API

Manage TP-Link Omada SDN Controllers via the Open API (OpenAPI 3.0.1).

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

Compatibility

兼容性

The Open API is available in Omada SDN Controller v5.9 and later (both the Software Controller and Cloud-Based Controller). Earlier versions only have an undocumented internal API that uses cookie-based session auth — this skill does not cover that legacy API.

The Open API feature must be explicitly enabled by an administrator before use.

该Open API在Omada SDN Controller v5.9及更高版本中可用（包括软件控制器和云控制器）。早期版本仅提供基于Cookie会话认证的未公开内部API——本技能不支持该遗留API。

使用前，必须由管理员明确启用Open API功能。

Environment Setup

环境设置

Before making any API calls, you need three environment variables. If the user has not provided these or a

.env

file does not exist, walk them through the setup:

Find the controller URL — Ask the user for their Omada Controller address. This is typically
```
https://<host>:8043
```
for the Software Controller. The port may differ if customized during installation.
Create API credentials — Guide the user to:
- Log into the Omada Controller web UI
- Navigate to Global View > Settings > Platform Integration > Open API
- Click Add New App
- Set the type to Client (not Gateway)
- Copy the generated Client ID and Client Secret

Create the
.env
file — Have the user create a

.env

file in the project root:

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

Never commit
.env
to git. Ensure

.gitignore

includes it.

Load variables before making requests:

bash

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

Do NOT use

source .env

— variables won't propagate to subshells or curl.

If auth fails, common causes are:

The Open API feature is not enabled on the controller
The client app type is set to Gateway instead of Client
The controller URL is wrong or missing the port
The client secret was rotated in the UI but not updated in
```
.env
```

在进行任何API调用之前，您需要三个环境变量。如果用户未提供这些变量或不存在

.env

文件，请引导他们完成以下设置：

查找控制器URL —— 询问用户他们的Omada Controller地址。对于软件控制器，通常为
```
https://<host>:8043
```
。如果安装时自定义了端口，端口号可能不同。
创建API凭证 —— 引导用户执行以下步骤：
- 登录Omada Controller网页UI
- 导航至全局视图 > 设置 > 平台集成 > Open API
- 点击添加新应用
- 将类型设置为客户端（而非网关）
- 复制生成的客户端ID和客户端密钥

创建
.env
文件 —— 让用户在项目根目录创建一个

.env

文件：

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

切勿将
.env
提交至git仓库。确保

.gitignore

文件中包含该文件。

在发起请求前加载变量：

bash

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

请勿使用

source .env

—— 变量不会传递到子shell或curl命令中。

如果认证失败，常见原因包括：

控制器上未启用Open API功能
客户端应用类型设置为网关而非客户端
控制器URL错误或缺少端口号
客户端密钥在UI中已更新，但
```
.env
```
文件中未同步

Locating the Wrapper Script

定位包装脚本

The API wrapper script is at

scripts/omada-api.sh

relative to this skill's directory. On first use in a session, find the script path using Glob to search for

**/omada-controller/scripts/omada-api.sh

. Use the discovered absolute path for all subsequent calls. For example, if the skill is installed at

.claude/skills/omada-controller/

, the script path is

.claude/skills/omada-controller/scripts/omada-api.sh

API包装脚本位于本技能目录下的

scripts/omada-api.sh

。在会话中首次使用时，使用Glob搜索

**/omada-controller/scripts/omada-api.sh

来查找脚本路径。所有后续调用均使用发现的绝对路径。例如，如果技能安装在

.claude/skills/omada-controller/

，则脚本路径为

.claude/skills/omada-controller/scripts/omada-api.sh

。

Making API Calls

发起API调用

Always use the wrapper script for all Omada API calls. It handles env loading, authentication, and URL construction automatically.

Anti-patterns: Any command beyond

bash <script> ...

triggers extra permission prompts. NEVER pipe, chain, or post-process script output with other commands. Use

--jq FILTER

for filtering and read the JSON output yourself for anything else. NEVER use curl, prefix assignments, or shell variables. Common anti-patterns:

```
bash <script> ... | jq ...
```
— use
```
--jq FILTER
```
flag instead

bash <script> ... | python3 -c "..."

— use

--jq

or read the output yourself

```
cat saved-response.txt | python3 -c "..."
```
— read the JSON yourself, do not shell out
```
curl -sk "${OMADA_URL}/api/info"
```
— use the script, not curl
```
SITE="123" && bash <script> ...
```
— inline the value directly in the path
```
SITE="123"; for mac in ...
```
— no shell variables or loops

On first use in a session, run the health check with no arguments. This verifies connectivity and lets the user approve the script once for all subsequent calls:

bash

bash <script>

Then make API calls:

bash

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

The path is relative to

/openapi/v1/{omadacId}

— no need to construct full URLs or manage tokens.

始终使用包装脚本进行所有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

bash <script>

然后发起API调用：

bash

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

路径是相对于

/openapi/v1/{omadacId}

的——无需构造完整URL或管理令牌。

Examples

示例

bash

undefined

bash

undefined

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

v2端点 —— 在路径前添加/v2

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

Fetch the OpenAPI spec for endpoint discovery

获取OpenAPI规范以发现端点

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

Filter API paths by keyword (use --jq, NEVER pipe)

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

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'

undefined

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

undefined

Path Routing

路径路由

The script routes paths automatically:

/sites/...

→

/openapi/v1/{omadacId}/sites/...

/v2/sites/...

→

/openapi/v2/{omadacId}/sites/...

```
/v3/api-docs
```
→
```
{OMADA_URL}/v3/api-docs
```
(no auth prefix)

脚本会自动路由路径：

/sites/...

→

/openapi/v1/{omadacId}/sites/...

/v2/sites/...

→

/openapi/v2/{omadacId}/sites/...

```
/v3/api-docs
```
→
```
{OMADA_URL}/v3/api-docs
```
（无认证前缀）

Recommended Permission

API Discovery

API发现

The controller hosts its own full OpenAPI 3.0.1 spec (~1,507 endpoints). Use it to discover any endpoint at runtime rather than hard-coding paths.

Swagger UI (browser):
```
{OMADA_URL}/swagger-ui/index.html
```
— no auth required

OpenAPI spec (JSON):

bash

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

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

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

OpenAPI规范（JSON）：

bash

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

Common Patterns

常见模式

Site ID

站点ID

Most endpoints are site-scoped. Get the site ID first:

bash

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

Then use it in subsequent paths:

/sites/{siteId}/devices

/sites/{siteId}/clients

, etc.

大多数端点是站点范围的。首先获取站点ID：

bash

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

然后在后续路径中使用该ID：

/sites/{siteId}/devices

、

/sites/{siteId}/clients

等。

Pagination

分页

Paginated endpoints accept

page

and

pageSize

query parameters and return:

json

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

分页端点接受

page

和

pageSize

查询参数，并返回以下格式：

json

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

API Versions

API版本

Some endpoints use

/v2/

instead of the default

/v1/

. The swagger spec includes both — prefix the path with

/v2

when needed.

某些端点使用

/v2/

而非默认的

/v1/

。Swagger规范包含这两种版本——必要时在路径前添加

/v2

。

Authentication Details

认证细节

The wrapper script handles auth automatically, but for reference:

Controller ID: Fetched from
```
GET {OMADA_URL}/api/info
```
(outside the OpenAPI spec)

Token: OAuth2 client credentials via

POST {OMADA_URL}/openapi/authorize/token?grant_type=client_credentials

with

omadacId

client_id

client_secret

in the JSON body (

grant_type

is a query param, not body)

Header format:

Authorization: AccessToken=<token>

(NOT

Bearer

)

Expiry: Tokens last 2 hours (7200 seconds) — the script re-authenticates each call

包装脚本会自动处理认证，但以下信息可供参考：

控制器ID：从
```
GET {OMADA_URL}/api/info
```
获取（不属于OpenAPI规范）
令牌：通过
```
POST {OMADA_URL}/openapi/authorize/token?grant_type=client_credentials
```
获取OAuth2客户端凭证，JSON请求体中包含
```
omadacId
```
、
```
client_id
```
、
```
client_secret
```
（
```
grant_type
```
是查询参数，而非请求体参数）

头部格式：

Authorization: AccessToken=<token>

（不是

Bearer

）

过期时间：令牌有效期为2小时（7200秒）——脚本每次调用都会重新认证

Gotchas

注意事项

Quoting: Always quote paths containing
```
&
```
(e.g.,
```
"/sites?page=1&pageSize=100"
```
). Unquoted
```
&
```
is a shell background operator.
TLS: The controller typically uses a self-signed cert. Always use
```
curl -k
```
.
MAC format: The API uses
```
AA-BB-CC-DD-EE-FF
```
(uppercase, dashes).
Error handling: Always check
```
errorCode
```
in responses.
```
0
```
= success, negative = error.

Token header:

Authorization: AccessToken=<token>

, NOT

Bearer <token>

引号：包含
```
&
```
的路径必须始终加引号（例如
```
"/sites?page=1&pageSize=100"
```
）。未加引号的
```
&
```
是shell后台操作符。
TLS：控制器通常使用自签名证书。请始终使用
```
curl -k
```
。
MAC格式：API使用
```
AA-BB-CC-DD-EE-FF
```
格式（大写，短横线分隔）。
错误处理：始终检查响应中的
```
errorCode
```
。
```
0
```
表示成功，负数表示错误。

令牌头部：

Authorization: AccessToken=<token>

，而非

Bearer <token>

。

References

参考资料

scripts/omada-api.sh — API wrapper (handles env, auth, and requests)
references/api-categories.md — API endpoint categories and counts
references/external-resources.md — Links to docs, examples, and integrations

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

omada-controller

Original

Translation

Omada SDN Controller API

Omada SDN Controller API

Compatibility

兼容性

Environment Setup

环境设置

Locating the Wrapper Script

定位包装脚本

Making API Calls

发起API调用

Examples

示例

List sites

列出站点

List devices at a site

列出站点中的设备

Reboot a device

重启设备

v2 endpoints — prefix path with /v2

v2端点 —— 在路径前添加/v2

Fetch the OpenAPI spec for endpoint discovery

获取OpenAPI规范以发现端点

Filter API paths by keyword (use --jq, NEVER pipe)

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

Extract just the data array from a paginated response

从分页响应中提取数据数组

Path Routing

路径路由

Recommended Permission

推荐权限设置

API Discovery

API发现

Common Patterns

常见模式

Site ID

站点ID

Pagination

分页

API Versions

API版本

Authentication Details

认证细节

Gotchas

注意事项

References

参考资料