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:

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

2. When data is an empty {}, reply: "None of the requested devices belong to the current user. No queryable devices are available."
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

Optional Configuration

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):

The script does not access any other network resources.

Quick Start

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

Query multiple devices (comma-separated):

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

Request Format

Request Body

Response Format

{
  "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:

Error Codes

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