Device Status Query API#

POST /api/device/status is used to batch query the online/offline status of devices.

⚠️ Display Rules (MUST be strictly followed)#

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

The script output includes the _device_names field (device_id → device_name mapping), which is used to display device names.

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

Device NameMAC AddressStatusLiving Room Cameraaabbccddeeff🟢 OnlineFront Door Camera112233445566🔴 Offline

Key rules:

• Look up the device name corresponding to device_id from _device_names; if not found, display "Unknown Device"
• device_id MUST be displayed as the MAC address after removing the xxxxS_ prefix
• Status mapping: "online" → 🟢 Online, "offline" → 🔴 Offline

1. When data is an empty {}, reply: "None of the requested devices belong to the current user. No queryable devices are available."
2. 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 ItemDelivery MethodDescriptionAI_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 ItemDelivery MethodDefault ValueDescriptionAI_GATEWAY_HOST~/.openclaw/.env``https://ai-open.icloseli.comGateway addressAI_GATEWAY_VERIFY_SSL~/.openclaw/.envtrueSet 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#

• The shared credential file ~/.openclaw/.env is readable by all skills under the same user. Ensure file permissions are restricted (e.g. chmod 600 ~/.openclaw/.env) and that only the OpenClaw service user has access. The IM clients write to this file under that user's home directory.
• TLS certificate verification is enabled by default. You MUST NOT disable it in production environments (disabling it introduces man-in-the-middle attack risks, and attackers may intercept API_KEY and device data)
• Before use, you MUST confirm that AI_GATEWAY_HOST points to a trusted domain
• You MUST use a least-privilege API_KEY to avoid reusing high-privilege credentials. This skill only requires device status query permission

Network Access Declaration#

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

EndpointMethodPurpose/api/device/listPOSTObtain device name mapping/api/device/statusPOSTQuery device online/offline status

The script does not access any other network resources.

Quick Start#

bash

python3 check_status.py --device-ids "xxxxS_aabbccddeeff"

Query multiple devices (comma-separated):

bash

python3 check_status.py --device-ids "xxxxS_aabbccddeeff,xxxxS_112233445566"

Request Format#

Request Body#

Parameter NameTypeRequiredDescriptiondevice_idsstring[]YesDevice ID list, cannot be an empty array. Format: xxxxS_<mac>

Response Format#

json

{
  "code": 0,
  "message": "success",
  "request_id": "<32-character request trace ID>",
  "data": {
    "xxxxS_aabbccddeeff": { "status": "online" },
    "xxxxS_112233445566": { "status": "offline" }
  },
  "_device_names": {
    "xxxxS_aabbccddeeff": "Living Room Camera",
    "xxxxS_112233445566": "Front Door Camera"
  }
}

data Field (Map Structure)#

The key is device_id, and the value is the status object:

Parameter NameTypeDescriptionstatusstringDevice status, value is "online" or "offline"

Error Codes#

Error CodeHTTP Status CodeDescription1001401api_key not provided1002401api_key is invalid or disabled2001400Missing required parameter ( device_ids is an empty array)3001502Internal gateway service call failed3002502Internal gateway service call failed3004502Internal gateway service call failed5000500Internal error

Notes#

• device_ids cannot be an empty array, otherwise error code 2001 is returned
• IMPORTANT: device_id is case-sensitive. The prefix MUST be lowercase xxxxS_, NOT uppercase XXXXS_. The script will auto-correct the case, but the agent SHOULD always pass the correct lowercase format
• Devices that do not belong to the current user are silently filtered and do not return an error
• Global request timeout is 120 seconds