@aqara-claw/aqara-open-api

OpenClaw plugin for Aqara Studio Open Platform APIs.

This plugin supports device discovery, status query, device control, and space management via the Aqara Studio Open API.

Features

• Unified API transport: all requests go through POST /open/api/v1 with type routing.
• Proxy bypass: uses a direct-connect HTTP agent so requests do not route through HTTP_PROXY or HTTPS_PROXY.
• IPv4 priority: forces dns.setDefaultResultOrder("ipv4first") to reduce DNS-related connection issues.
• Unified device cache: aqara_load_all_devices fetches devices, endpoints, traits, current values, and spaces in one call and reuses the cached result.
• Environment variable fallback: access_token can be provided via AQARA_OPEN_API_TOKEN.

Install

openclaw plugins install @aqara-claw/aqara-open-api

Upgrade

openclaw plugins update aqara-open-api

Example config

In ~/.openclaw/openclaw.json:

{
  "tools": {
    "profile": "full",
    "allow": ["*"]
  },
  "plugins": {
    "allow": ["aqara-open-api"],
    "entries": {
      "aqara-open-api": {
        "enabled": true,
        "config": {
          "endpoint_url": "https://xxx.aqara.cn",
          "access_token": "<YOUR_AQARA_OPEN_API_TOKEN>"
        }
      }
    }
  }
}

Configuration

| Option | Type | Default | Description | | --- | --- | --- | --- | | endpoint_url | string | — | Aqara Open Platform base URL. Requests go to {endpoint_url}/open/api/v1 | | access_token | string | — | Bearer token, or set AQARA_OPEN_API_TOKEN in env | | timeoutMs | number | 15000 | HTTP request timeout in milliseconds |

Request data specification

For tools that accept endpointId such as aqara_control_device:

• endpointId must be taken from the device info returned by aqara_load_all_devices.
• Do not create, invent, or guess an endpointId.
• deviceId, functionCode, and traitCode must also come from aqara_load_all_devices.

Agent Tools (7)

| Tool | Purpose | API Type | | --- | --- | --- | | aqara_load_all_devices | Load all devices with endpoints, traits, current values, and space info; cached after first call | GetAllDevicesWithSpaceRequest | | aqara_load_device_type_infos | Load all device types in the project with code and display name; cached after first call | GetDeviceTypeInfosRequest | | aqara_control_device | Control one or more device functions | ExecuteTraitRequest | | aqara_list_spaces | Query the full space tree | GetSpacesRequest | | aqara_create_space | Create a space | CreateSpaceRequest | | aqara_update_space | Update space name or spatial marking | UpdateSpaceRequest | | aqara-assign_devices_to_space | Associate devices to a space in batch | AssociateDevicesToSpaceRequest |

Typical workflow

1. aqara_load_all_devices         → Load device + endpoint + trait + space data into cache
2. aqara_control_device           → Control using IDs/codes from cache
3. aqara_list_spaces              → View full space hierarchy
4. aqara-assign_devices_to_space  → Associate devices to a space

Conversation examples

| User says | Tool to call | Notes | | --- | --- | --- | | "What devices do I have?" | aqara_load_all_devices | Returns all devices with full config and current values | | "Turn on the living room light" | aqara_control_device | Call aqara_load_all_devices first to get endpointId and trait info | | "What's the bedroom temperature?" | aqara_load_all_devices | Read the trait value directly from cached device data | | "Turn off all lights" | aqara_control_device | Batch control multiple devices using cached IDs and codes | | "Show my home space structure" | aqara_list_spaces | Returns the space tree | | "Put this device in the living room" | aqara-assign_devices_to_space | Associate a device to a space |

Skills

The plugin ships with a built-in skill at skills/aqara-open-api/SKILL.md that constrains the agent to:

• never guess deviceId, endpointId, functionCode, or traitCode
• always load real device data before control or state interpretation
• prefer filtering by deviceTypesList when the user asks by device type

Project structure

aqara-open-api/
├── index.ts
├── openclaw.plugin.json
├── package.json
├── tsconfig.json
├── skills/
│   └── aqara-open-api/
│       └── SKILL.md
└── src/
    ├── types.ts
    ├── config-schema.ts
    ├── runtime.ts
    ├── api-client.ts
    ├── store.ts
    └── tools/
        ├── schemas.ts
        ├── actions.ts
        └── index.ts

License

MIT