Home Assistant Integration v2.5 — OpenClaw Skill#

Control and query your Home Assistant smart home in plain English through Telegram or any OpenClaw channel.

Consent, safety & privacy (read before enabling)#

This skill controls physical devices and can retrieve private imagery from your home. Treat it accordingly:

• Every snippet that calls a service is gated in code, not just prose. The call_service, trigger_automation, camera_snapshot and send_notification snippets run through ha_confirm/ ha_call_service and will not act without an explicit confirmation token; lock/ alarm_control_panel are blocked unless you set HOME_ASSISTANT_ALLOW_LOCKS=true. ha_get/ ha_post are the low-level primitives these helpers build on and are not themselves gated — use the gated snippets (not a raw ha_post) for anything that calls a service. Read-only queries (summaries, sensor reads, listings) run without a gate.
• Cameras are private. get_cameras/ camera_snapshot return real images and reveal occupancy patterns. camera_snapshot is behind the same confirmation gate; snapshots are written owner-only ( 0600). Treat snapshot URLs and saved files as sensitive.
• Own-instance only. Point the skill only at a Home Assistant instance you own, with a token you control.
• Least-privilege token. Create a dedicated HA user with only the permissions your agent needs (avoid admin), store credentials chmod 600, and rotate/revoke the long-lived token periodically or if transport was ever insecure.
• Verify TLS. Use https://. For a self-signed cert, set HOME_ASSISTANT_CA_CERT to your CA so TLS is still verified — there is no option to disable certificate checking. Plain HTTP to a non-loopback host is refused unless you set HOME_ASSISTANT_ALLOW_HTTP=true (trusted LAN only, token sent unencrypted); loopback ( localhost/ 127.0.0.1/ ::1) is always allowed.

Setup#

1. Create a Home Assistant Long-Lived Token#

In Home Assistant: Profile (bottom-left) → Security → Long-Lived Access Tokens → Create Token

Copy the token immediately — it is only shown once.

2. Add credentials to openclaw.json#

json

{
  "env": {
    "HOME_ASSISTANT_URL":   "http://homeassistant.local:8123",
    "HOME_ASSISTANT_TOKEN": "your-long-lived-token-here"
  }
}

Using HTTPS with a self-signed certificate? Point at your CA cert so TLS is still verified:

json

"HOME_ASSISTANT_CA_CERT": "/path/to/your-ca.crt"

3. Restart OpenClaw#

Restart OpenClaw so it picks up the new env (however your install runs it):

bash

systemctl --user restart openclaw

4. Test#

Send your bot: home summary

Security Notes#

• Connects only to your configured HOME_ASSISTANT_URL — no third-party calls from this skill.
• Create a dedicated HA user with only the permissions your agent needs; rotate the token periodically.
• Store credentials in openclaw.json with restricted permissions ( chmod 600).
• This skill controls PHYSICAL devices (lights, heating, locks, switches) and can change their real-world state — state changes are gated in code ( ha_confirm), and lock/alarm control is off unless you opt in with HOME_ASSISTANT_ALLOW_LOCKS=true.
• Camera operations retrieve real images/snapshots from your home — gated by the same confirmation and written owner-only; treat snapshot URLs and saved files as private.
• TLS verification is always on. For a self-signed cert, set HOME_ASSISTANT_CA_CERT to your CA so HTTPS still verifies — there is no disable-verification option. Plain HTTP to a non-loopback host is refused unless HOME_ASSISTANT_ALLOW_HTTP=true (trusted LAN only).

What You Can Ask#

PhraseWhat happenshome summaryTemperatures, lights on, heating status, active switcheswhat is the temperature?All temperature sensorsturn off the living room lightsCalls light.turn_off (code-gated; confirm first)set the heating to 21 degreesCalls climate.set_temperature (code-gated; confirm first)is the EV charger on?Reads switch stateshow me the front door cameraReturns snapshot URL (capture is code-gated)list all automationsShows enabled/disabled automationsis anyone home?Reads presence/person entity stateswhat is my energy consumption?All power/energy sensorsturn on lights at 80% brightnessService call with brightness attribute (code-gated)

Act on explicit Home Assistant requests like these. Do not treat incidental mentions of bare words ("light", "camera", "door", "temperature") in ordinary conversation as commands — confirm intent, and never fire a state-changing or camera action off an ambiguous phrase.

Available Operations#

The skill provides 15 Python snippets executed via the OpenClaw exec tool:

• _load_config — loads credentials, sets up ha_get/ ha_post, and defines the ha_confirm/ ha_call_service safety gate (always runs first)
• check_api — tests HA connectivity
• ha_summary_for_telegram — full home summary
• get_temperature_sensors — all temperature sensors
• get_lights — lights with brightness levels
• get_switches — all switches with state
• get_climate — thermostat/climate status
• call_service — general-purpose: can call any HA service (turn_on/off, set_temperature, trigger, …). Routed through ha_call_service, which requires a confirmation token in code and blocks lock/ alarm_control_panel by default.
• search_entities — find entities by keyword
• get_cameras — camera list with snapshot URLs
• camera_snapshot — download a camera image (code-gated; writes to a secure tempfile.mkstemp path, owner-only 0600)
• get_automations — all automations with last-triggered
• trigger_automation — fire a specific automation (code-gated)
• get_energy — energy and power sensors
• send_notification — send via the user's own HA notify service only (code-gated by ha_confirm)

Skill File#

The full skill implementation is in home_assistant.json in this directory. It contains all 15 snippets as Python code that the agent executes via the Home Assistant REST API ( /api/states, /api/services/*). TLS verification is always on (self-signed certs via HOME_ASSISTANT_CA_CERT); state-changing service calls and camera snapshots run only through the in-code ha_confirm gate, and lock/alarm control is blocked unless explicitly enabled.

Troubleshooting#

HOME_ASSISTANT_TOKEN not configured Check the HOME_ASSISTANT_TOKEN in your openclaw.json env block and restart OpenClaw.

401 Unauthorized Token expired. Regenerate: HA → Profile → Security → Long-Lived Access Tokens.

SSL certificate verify failed Set HOME_ASSISTANT_CA_CERT to your CA cert so HTTPS verifies (the supported way to use a self-signed cert).

Connection refused Check HOME_ASSISTANT_URL is correct and HA is running.

A state change didn't happen State-changing calls are gated: call_service/ trigger_automation/ camera_snapshot run a dry-run first and print the exact pending action. Re-run with CONFIRM set to that exact string to proceed. For locks/alarms, also set HOME_ASSISTANT_ALLOW_LOCKS=true.

RuntimeError: Refusing to send the token over cleartext HTTP Your HOME_ASSISTANT_URL is http:// to a non-loopback host, so the long-lived token would cross the network unencrypted. Use https:// (with HOME_ASSISTANT_CA_CERT for a self-signed cert). On a trusted LAN you can allow plain HTTP with HOME_ASSISTANT_ALLOW_HTTP=true, but the token is then sent in the clear.