Closeli Open Device List Query

Device List Query API

POST /api/device/list is used to query all devices bound to the currently authenticated user. This API does not require a request body. The device list is automatically associated through the api_key.

⚠️ Display Rules (MUST Be Strictly Followed)

The script outputs structured data in JSON format, which is the expected behavior. The following display rules are formatting instructions for the agent: the agent MUST parse the JSON output from the script and convert it into a user-friendly format according to the rules below before displaying it, and MUST NOT display the raw JSON directly.

1. When code == 0 and data is not empty, display it as a table:

| MAC Address | Device Name | |----------|----------| | aabbccddeeff | Living Room Camera |

Key rule: device_id MUST remove the xxxxS_ prefix before being displayed as the MAC address. The table header MUST be written as "MAC Address" and MUST NOT be written as "Device ID".

2. When data is an empty array, reply: "There are no devices bound under the current account." 3. When code != 0, reply: "API call failed, error code {code}, reason: {message}"

Prerequisites

The script depends on httpx. If it is not installed, the script will prompt python3 -m pip install httpx.

Configuration Declaration

This skill depends on the following configuration items. The agent and user MUST confirm that they are correctly configured before running.

Required Configuration

| Configuration Item | Delivery Method | Description | |--------|----------|------| | AI_GATEWAY_API_KEY | ~/.openclaw/.env (persistent, written by OpenClaw clients), command line --api-key (temporary override) | API key used for API authentication. CLI flag takes precedence over the file when both present |

Optional Configuration

| Configuration Item | Delivery Method | Default Value | Description | |--------|----------|--------|------| | AI_GATEWAY_HOST | ~/.openclaw/.env | https://ai-open.icloseli.com | Gateway address | | AI_GATEWAY_VERIFY_SSL | ~/.openclaw/.env | true | Set to false to disable TLS certificate verification (development environments only) |

Configuration Source

The script reads ~/.openclaw/.env as the single persistent configuration source. This file is shared by all skills and uses the format KEY=VALUE (one entry per line). OpenClaw clients write to this file when the user updates settings. The script does NOT read any AI_GATEWAY_* environment variables — env variables are intentionally ignored to avoid stale Gateway-process snapshots overriding the user's latest config.

Security Notes

Network Access Declaration

This skill only accesses the following endpoints (all are paths under AI_GATEWAY_HOST):

| Endpoint | Method | Purpose | |------|------|------| | /api/device/list | POST | Query the list of devices bound to the user |

The script does not access any other network resources.

Quick Start

python3 list_devices.py

Authentication Method

Bearer Token authentication is used. The script automatically carries Authorization: Bearer in the request header.

Request Format

Request Headers

| Parameter Name | Type | Required | Description | |--------|------|------|------| | Content-Type | string | Yes | application/json | | Authorization | string | Yes | Bearer , a 32-character hexadecimal string |

Request Body

No request body is required.

Response Format

{
  "code": 0,
  "message": "success",
  "request_id": "<32-character request trace ID>",
  "data": [
    {
      "device_id": "xxxxS_aabbccddeeff",
      "device_name": "Living Room Camera"
    }
  ]
}

data Field (Device Array)

| Parameter Name | Type | Description | |--------|------|------| | device_id | string | Device ID, format: xxxxS_. All subsequent device APIs use this format | | device_name | string | Device name, a user-defined device alias |

Error Codes

| Error Code | HTTP Status Code | Description | |--------|------------|------| | 1001 | 401 | api_key not provided (missing Authorization header or incorrect format) | | 1002 | 401 | api_key is invalid or disabled | | 3001 | 502 | Internal gateway service call failed | | 3004 | 502 | Internal gateway service call failed | | 5000 | 500 | Internal error |

Notes

python3 list_devices.py

The script depends on httpx. If it is not installed, the script will prompt python3 -m pip install httpx.