Home Assistant Agent Interface

Six compact tools replace raw Home Assistant state dumps and repeated API calls. They let an OpenClaw agent discover the actual installation, understand current state and history, and execute any Home Assistant action available to the configured token.

What you can ask

• “What lights are on?”
• “Set the kitchen lights to 60%.”
• “Where is everyone?”
• “Find unavailable devices.”

The design follows Agent eXperience Interface (AXI) principles: semantic lookup, progressive detail, batched work, bounded results, explicit partial coverage, definitive empty results, and errors that help the agent correct its next call.

Changelog

Recent releases

• v0.4.3 — Makes release history visible on the marketplace listing and ships the complete changelog inside the package.
• v0.4.2 — Accepts canonical SecretRef credentials on stable and beta hosts, with real gateway-level regression coverage.
• v0.4.1 — Allows fresh stable installation before Home Assistant credentials are configured.
• v0.4.0 — Adds stable OpenClaw support and packed-artifact compatibility testing across stable and beta.

Read the complete changelog or browse every GitHub release. The published package also includes CHANGELOG.md for offline inspection.

What it provides

The plugin combines full action execution and live installation discovery with a bundled operating skill that teaches agents how to use the interface efficiently.

• home_assistant_find searches entities, actions, areas, devices, floors, and labels from Home Assistant itself.
• home_assistant_execute calls any domain.action with native Home Assistant target and data objects.
• Entity, device, area, floor, and label targets are supported without a plugin-maintained catalog.
• Action results include compact before/after observations when target entities can be resolved.
• Observation reads settle asynchronously: they stop as soon as a change appears or report that no change was observed within the bounded window.
• Exact dynamic attributes can be requested through home_assistant_inspect only when needed.
• The home-assistant-interface skill guides tool selection, discovery, execution, and honest interpretation of partial or asynchronous results.
• The plugin has no entity allowlist, action allowlist, approval system, or hard-coded household identities.

Home Assistant remains the source of truth for authorization. The plugin attempts the requested operation and Home Assistant permits or rejects it according to the configured user and token.

Tools

The bundled skill is an operating guide rather than another API surface. It loads with the enabled plugin, keeps direct control requests action-oriented, and avoids duplicating the tools' schemas in agent context.

Typical agent flow

Discover what the installation calls a light and which actions it offers:

{
  "query": "kitchen",
  "kinds": ["entity", "area", "action"],
  "domains": ["light"],
  "limit": 10
}

Turn on every compatible light in an area:

{
  "action": "light.turn_on",
  "target": { "area_id": ["kitchen"] },
  "data": { "brightness_pct": 60 }
}

The execution result includes Home Assistant's context ID plus bounded state observations for resolved target entities. The first post-action read happens immediately. If no change is visible, the plugin polls until a change appears or the settle deadline expires. For a multi-entity target, polling stops after the first observed target change, so slower targets may still be converging in the returned snapshot. observation.outcome distinguishes changed from no_change_observed, while attempts and waited_ms make the evidence explicit. A no-change observation does not redefine Home Assistant's successful action response.

Actions that do not target entities—notifications, conversations, some scripts, and similar operations—return observation.status: "not_applicable". If observation reads fail but Home Assistant accepts the action, the successful action is preserved and observation is reported as unavailable. Per-call settle_ms and poll_interval_ms values override the configured defaults; setting settle_ms to 0 restores a single immediate read.

Requirements

• OpenClaw 2026.7.1-2 or newer.
• A supported Node.js runtime: 22.22.3–22.x, 24.15.0–24.x, or 25.9.0 and newer.
• A reachable Home Assistant instance and a long-lived access token.

OpenClaw compatibility

The plugin is built with the 2026.8.1 beta 3 SDK and runtime-tested as a packed artifact against both host lines. Stable OpenClaw does not expose the newer output-schema field, but the result objects and plugin behavior are otherwise identical.

Install

From ClawHub

Install the latest reviewed release:

openclaw plugins install clawhub:homeassistant-agent-interface

From GitHub

Install the released tag:

openclaw plugins install git:github.com/fdsouvenir/homeassistant-agent-interface@v0.4.3

For local development:

git clone https://github.com/fdsouvenir/homeassistant-agent-interface.git
cd homeassistant-agent-interface
npm install
npm run plugin:build
openclaw plugins install -l .

Configure

Create a Home Assistant long-lived access token for the user whose permissions the agent should have. Prefer an OpenClaw SecretRef so the token does not need to be stored directly in openclaw.json.

Configure an environment-backed SecretRef through OpenClaw's CLI:

openclaw config set plugins.entries.homeassistant-agent-interface.config.token \
  --ref-source env \
  --ref-provider default \
  --ref-id HOME_ASSISTANT_TOKEN

The plugin schema accepts either a non-empty plaintext token or a canonical SecretRef object. OpenClaw stable supports env, file, and exec SecretRefs; 2026.8.1 beta 3 additionally supports store. OpenClaw retains the reference in configuration and materializes it before plugin registration. If a configured provider cannot resolve the reference, plugin loading fails instead of silently falling back to plaintext.

{
  plugins: {
    entries: {
      "homeassistant-agent-interface": {
        enabled: true,
        config: {
          baseUrl: "http://homeassistant.local:8123",
          token: {
            source: "env",
            provider: "default",
            id: "HOME_ASSISTANT_TOKEN",
          },

          // Optional ambient scopes. These examples are not defaults.
          briefEntities: [
            "sensor.example_temperature",
            "binary_sensor.example_door",
          ],
          presenceEntities: ["person.example"],
        },
      },
    },
  },
}

Restart or reload the Gateway after configuration, then inspect the runtime:

openclaw plugins inspect homeassistant-agent-interface --runtime

The plugin contains no default person, device, area, entity, zone, action, or Home Assistant URL. briefEntities and presenceEntities are optional operator-defined shortcuts used only when those tools receive no explicit targets.

Configuration reference

Agent-facing contract

• Every tool returns the same typed JSON on supported hosts; OpenClaw 2026.8.1 beta 3 and newer also receive the declared outputSchema.
• Success is explicit with ok: true; expected failures use ok: false with a stable code and focused recovery metadata.
• Collections report total, returned, and truncated where bounding matters.
• Discovery reports coverage.partial, available_kinds, and unavailable_kinds; a failed registry cannot masquerade as an authoritative empty result.
• Names are never guessed when the best match is ambiguous.
• home_assistant_find batches live service and registry discovery over one authenticated WebSocket session.
• home_assistant_execute uses Home Assistant's native call_service command rather than a hard-coded domain switch, then performs bounded early-exit observation polling.
• Unknown input fields fail schema validation.

Authority and transport

This plugin is an interface, not an authorization or household-safety layer. It does not classify actions, request approvals, or restrict entities/actions beyond Home Assistant's own token permissions. If the token can turn on a light, unlock a lock, run a script, or call a custom integration action, the plugin can request it.

Transport behavior is deliberately disciplined because failures and oversized results are bad agent interfaces: requests use the configured origin and base path, redirects are disabled for REST, cancellation and timeouts propagate, inbound data is capped, upstream shapes are checked, and credentials are never logged. See the operational model.

Development

Requires Node 22.22.3–22.x, 24.15.0–24.x, or 25.9.0+. Authoring uses the OpenClaw 2026.8.1 beta 3 SDK; compatibility tests install the packed artifact in isolated 2026.7.1-2 stable and 2026.8.1 beta 3 profiles, configure a canonical SecretRef, and invoke a tool through each real gateway.

npm install
npm run plugin:build
npm run plugin:validate
npm test
npm run compat
npm run check
npm pack --dry-run

Authoring commands use an isolated temporary OpenClaw state directory. They do not read or migrate the normal Gateway configuration.

See Architecture, Publishing, and Contributing.

Home Assistant is a trademark of the Open Home Foundation. This community project is not affiliated with or endorsed by the Open Home Foundation or OpenClaw.

License

MIT