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

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

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

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

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.