@aqara-claw/aqara-home-assistant

OpenClaw plugin for Home Assistant integration — device discovery, entity state reading, service calls, and event firing via the HA REST API.

Features

• Proxy bypass — uses a direct-connect HTTP agent so LAN requests never route through HTTP_PROXY / HTTPS_PROXY.
• IPv4 priority — forces dns.setDefaultResultOrder("ipv4first") to prevent connection failures when the OS resolver returns an IPv6 address for a LAN hostname.
• In-memory entity cache — reduces redundant API calls; cache is automatically populated on discovery and refreshed per-entity on demand.

Installation

// openclaw.config.json
{
  "plugins": {
    "allow": ["aqara-home-assistant"],
    "entries": {
      "aqara-home-assistant": {
        "enabled": true,
        "config": {
          "ha_url": "http://192.168.1.100:8123",
          "access_token": "<YOUR_LONG_LIVED_TOKEN>"
        }
      }
    }
  }
}

Configuration

| Option | Type | Default | Description | | -------------- | -------- | ------- | ------------------------------------------------------- | | ha_url | string | — | Home Assistant base URL (e.g. http://192.168.1.100:8123) | | access_token | string | — | Long-lived access token (HA → Profile → Security) | | timeoutMs | number | 15000 | HTTP request timeout in milliseconds |

Generating an access token: In Home Assistant, go to your user Profile → Security → Long-Lived Access Tokens → Create Token.

Agent Tools

| Tool | Purpose | Parameters | | --------------------------- | ---------------------------------- | ------------------------------------------------- | | ha_check_connection | Verify HA connectivity | (none) | | ha_discover_entities | Fetch & cache all entity states | (none) | | ha_get_entity_state | Get a single entity's state | entity_id | | ha_list_entities_by_domain| List entities for a domain | domain | | ha_call_service | Call an HA service | domain, service, service_data? | | ha_get_services | List available services | domain? | | ha_fire_event | Fire a custom event | event_type, event_data? |

Typical Workflow

1. ha_check_connection            → verify HA is reachable
2. ha_discover_entities           → populate the entity cache
3. ha_list_entities_by_domain     → e.g. domain="light" to see all lights
4. ha_get_entity_state            → e.g. entity_id="light.living_room"
5. ha_call_service                → e.g. domain="light", service="turn_on",
                                     service_data={"entity_id":"light.living_room","brightness":200}

Project Structure

aqara-home-assistant/
├── index.ts                  Plugin entry point
├── openclaw.plugin.json      Plugin metadata & config schema
├── package.json
├── tsconfig.json
└── src/
    ├── types.ts              TypeScript type definitions
    ├── config-schema.ts      Zod config validation
    ├── runtime.ts            Plugin runtime singleton
    ├── ha-client.ts          HA REST API client (proxy bypass + IPv4 priority)
    ├── store.ts              In-memory entity cache
    └── tools/
        ├── schemas.ts        TypeBox tool parameter schemas
        ├── actions.ts        Tool execution logic
        └── index.ts          Tool registration & config resolution

License

MIT