Connecting Your OpenClaw Agent to Home Assistant
Home Assistant is the undisputed king of open-source smart home platforms. It runs on over 2 million installations, supports 2,700+ integrations, and gives you local control over everything from light bulbs to industrial HVAC systems. But its automation engine has a fundamental limitation: it can only do what you explicitly tell it to do, one rule at a time.
An OpenClaw agent connected to Home Assistant changes the game. Instead of writing YAML automations for every possible scenario, you give your agent access to your home's devices and sensors, and it reasons about what to do. The agent sees the full picture: time of day, weather forecast, occupancy patterns, energy prices, and device states, and makes decisions that no static rule set could match.
This guide walks you through connecting your OpenClaw agent to Home Assistant using ClawTether, from initial setup to your first intelligent automation.
## What You Will Need
Before you start, make sure you have these pieces in place:
- **A running Home Assistant instance.** Any installation method works: Home Assistant OS, Container, Supervised, or Core. You need admin access to create long-lived access tokens. - **An OpenClaw agent.** Any agent with a valid SOUL.md and AGENTS.md. If you do not have one yet, the OpenClaw quickstart guide gets you running in 15 minutes. - **ClawTether installed.** ClawTether runs as a bridge between your agent and your IoT devices. Install it alongside your OpenClaw instance. [Get started with ClawTether](/try) if you have not set it up yet. - **Network access.** Your OpenClaw agent and Home Assistant need to be on the same network, or you need to configure remote access through Home Assistant's built-in tunnel or a reverse proxy.
## Step 1: Generate a Home Assistant Access Token
Your OpenClaw agent authenticates with Home Assistant using a long-lived access token. This is a one-time setup that gives your agent API access without needing your login credentials.
In Home Assistant, navigate to your profile page (click your username in the sidebar). Scroll to the bottom to the "Long-Lived Access Tokens" section. Click "Create Token," give it a descriptive name like "OpenClaw Agent," and copy the token immediately. You will not be able to see it again.
**Security note:** This token grants full API access to your Home Assistant instance. Treat it like a password. Store it in your agent's credential manager (ClawCoil if you use it) rather than in environment variables or configuration files. If the token is compromised, anyone with network access to your Home Assistant instance can control your devices.
## Step 2: Configure ClawTether's Home Assistant Connector
ClawTether uses a connector model where each IoT platform gets its own connector plugin. The Home Assistant connector handles all communication with your instance through both the REST API (for state queries and commands) and the WebSocket API (for real-time event streaming).
Add the Home Assistant connector to your ClawTether configuration with your instance URL and the access token from Step 1. ClawTether will immediately attempt to connect and discover all available entities.
**What gets discovered.** ClawTether imports every entity Home Assistant knows about: lights, switches, sensors, climate devices, locks, covers, media players, automations, scripts, and scenes. Each entity becomes a tool your agent can call. A typical Home Assistant installation has 50-300 entities, so your agent gets a lot of capabilities in one step.
**Filtering entities.** You probably do not want your agent to see every entity. Test switches, developer tools, and internal automations add noise. ClawTether's entity filter lets you include or exclude entities by domain (all lights, no automations), by area (only living room and kitchen), or by individual entity ID. Start narrow and expand as you build confidence.
## Step 3: Set Granular Permissions
This is the most important step and the one most people rush through. Your agent's permissions determine what it can read and what it can control. Getting this right is the difference between a helpful home assistant and a liability.
ClawTether's permission model has three levels:
- **Read-only.** The agent can see the entity's state but cannot change it. Use this for sensors, weather data, energy monitors, and any device where you want awareness without control. - **Control.** The agent can read state and send commands (turn on, turn off, set temperature, etc.). Use this for lights, thermostats, and media players where automated control is useful and low-risk. - **Restricted.** The agent cannot see or interact with the entity at all. Use this for security devices, locks, and anything where unauthorized control would be dangerous.
**Start with read-only everywhere.** Let your agent observe your home for a few days before giving it control over anything. Review the observations it makes and the actions it suggests. If its suggestions are sensible, upgrade specific devices to control access. This incremental approach builds trust without risking unintended actions.
**Permissions for locks and security.** Our strong recommendation: keep locks, alarm systems, and garage doors on restricted or read-only for at least the first month. These devices have irreversible consequences if controlled incorrectly. An agent that accidentally turns off a light is a minor annoyance. An agent that accidentally unlocks your front door is a security incident.
## Step 4: Your First Intelligent Automation
With ClawTether connected and permissions configured, your agent can start interacting with your home. Let us build a simple but genuinely useful automation: an intelligent "leaving home" routine.
**The traditional approach** requires you to write a Home Assistant automation that triggers when your phone disconnects from Wi-Fi. It runs a fixed script: turn off all lights, lower the thermostat, lock the doors, arm the security system. Same actions every time, regardless of context.
**The agent approach** is different. Your agent notices you have left (phone disconnected from Wi-Fi, no motion detected for 10 minutes) and assesses the situation before acting:
- Are all windows closed? If not, skip closing the blinds on open windows to maintain airflow. - Is the washing machine running? If so, leave the laundry room power on and set a reminder to check it. - Is anyone else home? If your partner's phone is still on Wi-Fi, skip the thermostat change and the security arm. - What is the weather forecast? If rain is expected, close the skylight. If it is a clear day, leave the solar-facing blinds open for passive heating.
None of this requires you to write rules for each scenario. The agent reasons through the current state and makes appropriate decisions. You define the intent ("when I leave, secure the house appropriately") and the agent figures out what "appropriately" means in context.
## Step 5: Event-Driven Responses
Beyond automations you initiate, ClawTether's WebSocket connection streams real-time events from Home Assistant to your agent. This enables reactive behavior: your agent responds to things that happen in your home as they happen.
**Motion-based lighting.** Your agent receives motion sensor events and controls lights based on context. Motion in the hallway at 2 AM gets a dim nightlight. Motion in the kitchen at 7 AM gets full brightness. The agent knows the difference because it tracks time, recent activity patterns, and ambient light levels.
**Energy management.** If you have smart plugs with energy monitoring, your agent can track consumption patterns and alert you to anomalies. The dryer normally runs for 45 minutes. If it has been running for 90 minutes, something might be wrong. Your agent can send you a notification and offer to turn off the outlet remotely.
**Environmental monitoring.** Temperature and humidity sensors feed your agent a continuous picture of your home's environment. If the basement humidity spikes (indicating a potential leak), the agent can alert you immediately rather than waiting for you to notice a damp spot next week.
## Debugging Common Issues
A few issues come up regularly when connecting OpenClaw agents to Home Assistant.
**Entity not found errors.** If your agent tries to control a device and gets an entity not found error, the entity ID in Home Assistant has probably changed. Home Assistant regenerates entity IDs when devices are re-added or renamed. Run ClawTether's discovery command to refresh the entity list.
**Slow response times.** If device commands take more than a couple seconds, check your network path. ClawTether communicates over HTTP/WebSocket. If your Home Assistant instance is behind a slow reverse proxy or a congested network segment, commands will lag. For time-sensitive automations (like motion-activated lights), ensure ClawTether and Home Assistant are on the same LAN segment.
**Agent making unexpected decisions.** If your agent is taking actions you did not expect, the issue is almost always permissions being too broad. Check which entities have control access and narrow the scope. Also review your agent's SOUL.md to make sure its home automation instructions are specific enough. Vague instructions like "keep the house comfortable" leave too much room for interpretation.
## Privacy and Local Processing
One of the biggest advantages of the OpenClaw plus Home Assistant plus ClawTether stack is that everything can run locally. No device data needs to leave your network. Your agent processes sensor readings, makes decisions, and sends commands, all on your local hardware.
ClawTether's local-first architecture means your smart home keeps working even if your internet connection drops. The agent switches to offline mode with reduced capabilities (no weather forecasts, no remote notifications) but continues handling local automations and device control.
For users who want remote access, ClawTether supports an encrypted tunnel that exposes your agent's interface securely without opening ports on your router. But local-only operation is the default and the recommended configuration for maximum privacy.
## Getting Started with ClawTether
ClawTether makes connecting OpenClaw agents to Home Assistant straightforward. The Home Assistant connector handles discovery, authentication, and real-time event streaming out of the box. Granular permissions give you full control over what your agent can see and do. And local-first processing keeps your home data private. Visit [clawtether.com/try](/try) to set up the bridge and give your OpenClaw agent eyes and hands in the physical world.