Connecting OpenClaw to Home Assistant: A Real Setup Walkthrough
I spent a weekend getting OpenClaw talking to my Home Assistant instance through ClawTether. The official docs cover the happy path well enough, but I ran into a handful of problems that aren't documented anywhere. This is the guide I wish I'd had.
## What you need before starting
You'll need a running Home Assistant instance (I'm on 2025.12, but anything from 2025.8 should work), an OpenClaw agent with at least version 0.14, and ClawTether installed as a bridge module. You also need network access between the machine running your agent and your Home Assistant box. Sounds obvious, but if your agent runs in a container and HA is on a different VLAN, you'll hit a wall before you start.
## Step 1: Generate a long-lived access token
In Home Assistant, go to your profile (click your name in the sidebar), scroll to the very bottom, and create a long-lived access token. Copy it immediately. You won't see it again.
One thing the docs don't mention: if you have two-factor auth enabled on your HA account, the token still works without 2FA. The token bypasses the login flow entirely. This is by design, but it surprised me.
## Step 2: Configure the ClawTether connector
In your OpenClaw config directory, create or edit the `clawtether.yaml` file:
```yaml connectors: home_assistant: url: http://192.168.1.100:8123 token: your-long-lived-token-here discovery: true subscribe_events: true ```
Set `subscribe_events` to true if you want real-time state changes pushed to your agent. I'd recommend starting with it off and turning it on later. The event firehose from a busy HA instance is noisy, and your agent will burn tokens processing state changes for devices you don't care about.
## Step 3: Run discovery
```bash openclaw tether discover ```
This scans your HA instance and lists every entity it finds. On my setup (about 80 devices), discovery took around 4 seconds. The output is a JSON dump of entity IDs, friendly names, and current states. Pipe it to a file if you want to review it later.
Here's where I hit my first real problem. Discovery found 247 entities, not 80. That's because HA creates multiple entities per device. A single smart plug might have a switch entity, a power monitoring entity, a voltage entity, and a firmware update entity. ClawTether imports all of them by default.
## Step 4: Filter what your agent can see
You don't want your agent reasoning about 247 entities. Edit the connector config to include only what matters:
```yaml connectors: home_assistant: url: http://192.168.1.100:8123 token: your-long-lived-token-here discovery: true subscribe_events: true include_domains: - light - climate - sensor - lock exclude_entities: - sensor.hacs - sensor.supervisor_updates ```
The `include_domains` filter cut my entity count from 247 to around 60. The `exclude_entities` list handles the stragglers that slip through domain filtering.
## Step 5: Set permissions
This is the part people skip, and then regret. ClawTether has a permissions layer that controls what your agent can read vs. control. My recommendation:
- Start with read-only on everything - Add write access to lights first (low stakes if something goes wrong) - Add climate control after a few days - Save locks and security for when you trust the setup
```yaml permissions: light.*: read_write climate.*: read_only lock.*: read_only sensor.*: read_only ```
## What actually works well
Lights are rock solid. I can say "turn off all the lights downstairs" and the agent maps "downstairs" to the correct HA area and sends the right service calls. It handles brightness, color temperature, and RGB without issues.
Sensor reading is reliable too. "What's the temperature in the bedroom?" returns the current reading from my Aqara temperature sensor instantly. The agent can also do basic trend analysis: "Has the humidity been going up today?" works if you have the HA history component enabled.
Climate control works, but with a caveat. The agent can set target temperatures and switch modes (heat, cool, auto), but HVAC systems respond slowly. If you say "make it warmer" and the agent bumps the thermostat by 2 degrees, it takes 20 minutes to see a result. The agent doesn't always understand that patience is needed here.
## What's still flaky
**Event subscriptions drop silently.** About once a week, the WebSocket connection between ClawTether and HA dies without an error. Your agent keeps running but stops getting state updates. I wrote a cron job that pings the connection every 5 minutes and restarts the bridge if it's dead. Not elegant, but it works.
**Area mapping is inconsistent.** HA's area registry is optional, and a lot of devices don't have area assignments. If you say "turn off the kitchen lights" and only two of your three kitchen lights are assigned to the Kitchen area in HA, the third stays on. Fix this in HA first: make sure every device has an area.
**Locks are scary.** They work technically, but having an AI agent control your door locks requires a level of trust I haven't reached. I keep locks at read-only so the agent can tell me if a door is locked, but can't unlock it.
## Example automations worth setting up
Here are three I actually use daily:
**Morning briefing.** "Good morning" triggers the agent to read the outside temperature, check my calendar (through a separate skill), turn on the kitchen lights to 60% warm white, and start the coffee machine (smart plug).
**Away mode.** When no motion is detected for 30 minutes across all indoor sensors, the agent offers to switch to away mode. Away mode lowers the thermostat, turns off all lights, and locks the front door (ok, I enabled lock write access for this one specific automation, with a confirmation prompt).
**Bedtime wind-down.** At 10 PM, the agent dims all lights to 20%, switches them to warm white (2700K), and asks if I want to set an alarm for the morning.
## Honest assessment
ClawTether's Home Assistant integration is genuinely useful for day-to-day stuff. Lights and sensors work great. Climate is fine with patience. The WebSocket reliability issue is annoying but manageable. If you're the kind of person who already runs Home Assistant, the setup takes about an hour, and the payoff is real. Just don't give your agent the keys to your front door on day one.