Home Assistant Skill for OpenClaw

OpenClaw Home Assistant Skill Overview

The Home Assistant skill connects OpenClaw to your Home Assistant instance, turning your AI agent into a powerful smart home controller. Instead of navigating dashboards or editing YAML configuration files, you can manage your entire smart home through natural language — toggle lights, check sensor readings, create automations, and troubleshoot device issues, all from your terminal.

Home Assistant is the world's largest open-source home automation platform, supporting over 2,000 integrations with devices from Philips Hue, Zigbee, Z-Wave, Matter, and hundreds more. The OpenClaw Home Assistant skill leverages the Home Assistant REST API to give your agent direct access to entities, services, automations, and scripts running on your instance.

Typical workflow:

1. Ask OpenClaw to turn off all living room lights and set the thermostat to 20°C.
2. The agent calls the Home Assistant API, identifies the relevant entities, and executes the service calls.
3. Confirmation is returned instantly — no need to open the Home Assistant app or dashboard.

This skill is ideal for developers who already run Home Assistant and want faster, scriptable access to their smart home. It pairs well with the Slack skill for sending smart home notifications to your team channels, and integrates naturally with Docker-based deployments if you run Home Assistant in a container.

Prerequisites for Home Assistant Skill

Before installing the Home Assistant skill, make sure you have:

• OpenClaw installed and running (v1.0+)
• A Home Assistant instance (v2023.1+) accessible over the network — installation guide
• A Long-Lived Access Token generated from your Home Assistant profile
• Network access from your machine to the Home Assistant instance (local or remote)
• clawhub CLI installed for skill management

Verify your setup:

# Check OpenClaw version
openclaw --version

# Test Home Assistant API connectivity
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://YOUR_HA_HOST:8123/api/ | head -1

# Check clawhub CLI
clawhub --version

If the API returns {"message": "API running."}, your Home Assistant instance is ready.

How to Install the Home Assistant Skill

Install the Home Assistant skill with a single command:

npx clawhub@latest install home-assistant

To verify the installation:

clawhub list

You should see home-assistant in the list of installed skills. Install with clawhub CLI for the fastest setup experience.

Home Assistant Skill Configuration

The skill requires a Home Assistant URL and a long-lived access token to authenticate API requests.

Generate a Long-Lived Access Token

1. Open your Home Assistant dashboard at http://YOUR_HA_HOST:8123.
2. Click your profile icon (bottom-left corner).
3. Scroll to Long-Lived Access Tokens and click Create Token.
4. Name it openclaw-agent and copy the generated token.

Environment Setup

Set the following environment variables:

# Home Assistant instance URL (include port if non-standard)
export HOMEASSISTANT_URL="http://192.168.1.100:8123"

# Long-lived access token
export HOMEASSISTANT_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6..."

You can add these to your shell profile (~/.bashrc, ~/.zshrc) or use a .env file with a secret manager.

Important: Never hardcode tokens in configuration files or commit them to version control. Use environment variables or a dedicated secret manager like 1Password.

Optional: Remote Access

If your Home Assistant instance is not on the same network, configure remote access via:

| Method | Description | |--------|-------------| | Nabu Casa | Home Assistant Cloud — easiest option, provides a remote URL | | Reverse proxy | Nginx or Caddy with SSL termination | | Tailscale/WireGuard | VPN tunnel for secure LAN-like access |

Home Assistant Skill Usage Examples

1. Control Lights and Devices

You: "Turn off all lights in the bedroom and set the living room brightness to 40%."

The agent calls light.turn_off for bedroom entities and light.turn_on with brightness_pct: 40 for living room lights. It identifies entities by room assignment and returns a confirmation summary.

2. Query Sensor Data

You: "What's the current temperature in the office and the total energy usage today?"

The agent queries sensor.office_temperature and sensor.energy_daily entities, returning formatted readings: "Office temperature: 22.3°C. Today's energy usage: 14.7 kWh." It handles unit conversions and formats data for readability.

3. Create an Automation

You: "Create an automation that turns on the porch light at sunset and turns it off at 11 PM every night."

The agent builds a Home Assistant automation using the sun trigger for sunset and a time trigger for 23:00. It registers the automation via the API, assigns a descriptive name, and confirms it is enabled.

4. Activate Scenes

You: "Activate the movie night scene."

The agent calls scene.turn_on for scene.movie_night, which dims lights, closes blinds, and sets the media player to the correct input — all configured in your existing scene definition.

5. Troubleshoot Device Status

You: "Which devices are currently unavailable or offline?"

The agent queries all entities with a unavailable or unknown state, groups them by integration, and returns a diagnostic report: "3 devices offline — Zigbee motion sensor (last seen 2h ago), Smart plug kitchen (unreachable), Weather integration (API timeout)."

Security & Best Practices

Follow these guidelines to keep your smart home secure:

• Use least privilege. Create a dedicated Home Assistant user for OpenClaw with permissions limited to the rooms and devices you want the agent to control. Avoid using your admin account token.
• Review before confirming. The agent will describe what it plans to do before executing destructive actions like deleting automations or disabling integrations. Always review the action summary.
• Secure your token. Long-lived access tokens provide full API access. Store them in environment variables, never in plain text files. Rotate tokens periodically from your Home Assistant profile.
• Use HTTPS. If accessing Home Assistant remotely, always use HTTPS with a valid SSL certificate. Never expose your instance on the public internet without encryption.
• Restrict network access. Limit API access to trusted IP ranges using Home Assistant's ip_bans or firewall rules. Review the Safety Checklist for general OpenClaw security guidance.

Troubleshooting Common Errors

"401 Unauthorized — Invalid access token"

The long-lived access token is invalid or expired.

1. Verify the token is set correctly:

echo $HOMEASSISTANT_TOKEN

2. Generate a new token from your Home Assistant profile page.
3. Ensure there are no extra whitespace or line breaks in the token value.

"Connection refused — Cannot reach Home Assistant"

The agent cannot connect to your Home Assistant instance.

1. Verify the URL is correct and includes the port:

curl -s http://YOUR_HA_HOST:8123/api/

2. Check that Home Assistant is running: sudo systemctl status homeassistant (for supervised installs).
3. If using Docker, confirm the container is running: docker ps | grep homeassistant.
4. Check firewall rules — port 8123 must be accessible from your machine.

"Entity not found — light.living_room"

The entity ID does not match any device in Home Assistant.

1. List all available entities:

curl -s -H "Authorization: Bearer $HOMEASSISTANT_TOKEN" \
  http://YOUR_HA_HOST:8123/api/states | jq '.[].entity_id' | grep light

2. Entity IDs are case-sensitive and use underscores — check for typos.
3. If the device was recently added, restart Home Assistant to refresh entity registration.