How to Connect OpenClaw to Home Assistant (Complete Integration Guide)

Why Connect OpenClaw to Home Assistant?

Before we get into the how, let's talk about the why. Home Assistant is already powerful — it supports over 2,000 integrations and has a robust automation engine. So what does OpenClaw actually add?

**The Limitations of Traditional Home Automation**

Standard Home Assistant automations follow a rigid trigger → condition → action pattern. They're great for "when motion detected, turn on lights" but struggle with nuance.

**What OpenClaw Adds**

Home Assistant alone offers automations and scenes for light control, scheduled thermostats for climate, motion alerts for security, static YAML automations for routines, basic commands via Assist for voice control, and manual log checking for troubleshooting. With OpenClaw added, you get natural language plus context-aware scenes, AI-optimized climate based on occupancy, weather, and preferences, intelligent alert triage that ignores the cat and escalates unknowns, dynamic routines that adapt to your schedule, conversational AI with memory and follow-ups, and proactive anomaly monitoring and reporting.

The combination is more than additive. OpenClaw becomes the "brain" that orchestrates your Home Assistant "body."

• Context awareness: A traditional automation can't know you're working from home today and should keep the office lights on
• Natural language control: You can describe what you want in plain English instead of writing YAML
• Multi-step reasoning: "Make the house ready for a dinner party" involves dozens of coordinated actions
• Learning from feedback: When you say "it's too bright," the agent remembers your preference

Prerequisites

Before starting, make sure you have the following. If you're running Home Assistant Container (Docker) without Supervisor, you'll need to run OpenClaw as a separate Docker container and connect via the REST API instead.

• Home Assistant OS (HAOS) or Home Assistant Supervised — the add-on requires the Supervisor
• Hardware: Any system running HAOS — Raspberry Pi 4/5, Intel NUC, Proxmox VM, etc.
• At least 2GB free RAM — OpenClaw runs alongside Home Assistant
• An AI provider API key — Anthropic (Claude), OpenAI, Google (Gemini), or a local model via Ollama
• Network access — the add-on needs to reach your AI provider (unless using local models)

Step 1: Install the OpenClaw Home Assistant Add-on

The community-maintained add-on (techartdev/OpenClawHomeAssistant) has 247+ GitHub stars and supports amd64, aarch64, and armv7 architectures.

**Add the Repository**

In Home Assistant, navigate to Settings → Add-ons → Add-on store. Click the ⋮ menu (top-right) → Repositories. Paste the repository URL and click Add → Close. Refresh the page — you should see OpenClaw Assistant in the add-on list. Click Install. The installation takes 3-10 minutes depending on your hardware (the Docker image includes Chromium, Node.js, and various CLI tools).

**Start the Add-on**

After installation, click Start. Navigate to the add-on's Info tab. You'll see a landing page with an Open Gateway Web UI button and an embedded web terminal.

Important: The Gateway Web UI opens in a separate tab because Home Assistant's Ingress proxy doesn't fully support WebSocket connections.

https://github.com/techartdev/OpenClawHomeAssistant

Step 2: Run Onboarding

Open the embedded terminal in the add-on page and run the onboarding command. The interactive wizard guides you through AI provider selection (choose Claude, GPT-4, Gemini, or configure a local model), API key entry, channel setup (optionally connect Telegram or Discord for remote control), and basic preferences (timezone, language, agent name).

For more granular control, you can also run the configure command.

**Retrieve Your Gateway Token**

You'll need the gateway token for API access and the web UI. Save this token somewhere safe — you'll use it for both the web UI and Home Assistant API calls.

**Verify the Installation**

You should see output confirming the gateway is running on port 18789. Click Open Gateway Web UI, paste your token when prompted, and you should see the OpenClaw dashboard.

openclaw onboard

openclaw configure

jq -r '.gateway.auth.token' /config/.openclaw/openclaw.json

openclaw gateway status

Step 3: Configure Secure Access

OpenClaw requires a secure context (HTTPS or localhost) for the Gateway Web UI since version 2026.2.21. The add-on provides several access modes: lan_https (best for most users, mobile access, low complexity with auto-generated TLS certificates), lan_reverse_proxy (for users with Nginx Proxy Manager/Caddy, medium complexity where your proxy handles TLS), tailnet_https (for Tailscale users, medium complexity using Tailscale certificates), and local_only (terminal/SSH only, lowest complexity with loopback only).

**Recommended: Built-in HTTPS (lan_https)**

This is the simplest approach and works great for phone/tablet access. Go to Settings → Add-ons → OpenClaw Assistant → Configuration. Set access_mode to lan_https. Restart the add-on. The add-on automatically generates a local CA certificate and TLS server certificate.

For Android: Download the CA certificate from the add-on landing page. Go to Settings → Security → Install certificate → CA certificate. Select the downloaded file.

For iOS: Open the .crt file from the add-on page. Install Profile when prompted. Go to Settings → General → About → Certificate Trust Settings. Enable the OpenClaw CA.

**Alternative: SSH Port Forwarding (Zero Config)**

If you only need access from your computer, use SSH port forwarding. Then open http://localhost:18789 — localhost counts as a secure context. For Tailscale users, set access_mode to tailnet_https and use your Tailscale HTTPS certificates.

ssh -L 18789:127.0.0.1:18789 your-user@your-ha-ip

Step 4: Connect OpenClaw to Home Assistant's API

Now for the fun part — making OpenClaw actually control your smart home. There are two approaches: the Assist Pipeline integration and the REST API skill.

**Option A: Assist Pipeline (Voice/Conversation Agent)**

The add-on supports Home Assistant's Assist pipeline, making OpenClaw a conversation agent. In Home Assistant, go to Settings → Voice assistants. Click Add assistant. Set the conversation agent to OpenClaw (it appears after the add-on exposes its OpenAI-compatible API). Configure your preferred speech-to-text and text-to-speech engines. Save. Now you can talk to OpenClaw through any Assist-compatible device — voice satellites, the HA app, or dashboard cards.

**Option B: REST API Skill (Full Control)**

For deeper integration, create an OpenClaw skill that calls Home Assistant's REST API. First, generate a Long-Lived Access Token in Home Assistant: go to your Profile (http://your-ha:8123/profile), scroll to Long-Lived Access Tokens, click Create Token, name it "OpenClaw", and copy the token.

Now create the skill file in the OpenClaw terminal. Then store your HA token. Now OpenClaw can control any Home Assistant entity. Ask it: "Turn off all lights in the living room" or "Set the thermostat to 21 degrees" and it will make the appropriate API calls.

mkdir -p /config/clawd/skills/homeassistant
cat > /config/clawd/skills/homeassistant/SKILL.md << 'EOF'
# Home Assistant Control Skill

## Description
Control Home Assistant entities via the REST API.

## Configuration
- HA_URL: http://localhost:8123
- HA_TOKEN: (stored in /config/secrets/homeassistant.token)

## Commands

### List all entities
```bash
curl -s -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/states | jq '.[].entity_id'
```

### Get entity state
```bash
curl -s -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  -H "Content-Type: application/json" \
  http://localhost:8123/api/states/ENTITY_ID | jq '{state: .state, attributes: .attributes}'
```

### Call a service
```bash
curl -s -X POST \
  -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "ENTITY_ID"}' \
  http://localhost:8123/api/services/DOMAIN/SERVICE
```

### Common services
- Turn on: `light/turn_on`, `switch/turn_on`, `climate/turn_on`
- Turn off: `light/turn_off`, `switch/turn_off`
- Set temperature: `climate/set_temperature` with `{"entity_id": "...", "temperature": 22}`
- Set brightness: `light/turn_on` with `{"entity_id": "...", "brightness": 200}`
- Lock/unlock: `lock/lock`, `lock/unlock`
- Open/close cover: `cover/open_cover`, `cover/close_cover`
EOF

echo "YOUR_LONG_LIVED_TOKEN" > /config/secrets/homeassistant.token
chmod 600 /config/secrets/homeassistant.token

Step 5: Build Smart Automations with OpenClaw

Here's where the integration really shines. Instead of writing YAML automations, you can describe what you want in natural language and let OpenClaw handle the orchestration.

**Example 1: Morning Routine**

Tell OpenClaw: "Every weekday at 6:30 AM, check the weather. If it's cold (below 10°C), turn on the hallway heater 30 minutes before I usually wake up. Turn on the kitchen lights at 50% brightness. Start the coffee maker if it's plugged in." OpenClaw can implement this using cron jobs. The key difference from a YAML automation: OpenClaw adapts. If you sleep in on a holiday, tell it "I'm sleeping in today" and it skips the routine. Try doing that with YAML.

**Example 2: Energy Optimization**

OpenClaw can monitor your energy usage and make intelligent decisions. The agent can learn patterns: "Electricity is expensive between 4-7 PM. Pre-cool the house at 3:30 PM and reduce HVAC during peak hours. Shift the dishwasher and washing machine to run after 9 PM."

**Example 3: Security Intelligence**

Instead of getting every motion alert, let OpenClaw triage. Tell the agent: "Only alert me about front door motion between 11 PM and 6 AM, or if I'm marked as away. During the day, log it but don't bother me unless there's motion for more than 5 minutes continuously." This kind of conditional, context-aware logic would require complex YAML templates. With OpenClaw, it's a conversation.

# Query energy sensors
curl -s -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  http://localhost:8123/api/states/sensor.energy_total_consumption | jq '.state'

# Check electricity price (if you have a price sensor)
curl -s -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  http://localhost:8123/api/states/sensor.electricity_price | jq '.state'

# Monitor motion sensors
curl -s -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  http://localhost:8123/api/states/binary_sensor.front_door_motion | jq '.state'

Architecture: How It All Fits Together

Understanding the architecture helps with troubleshooting and advanced configurations.

**Services Inside the Add-on**

The add-on runs three services: OpenClaw Gateway on port 18789 (configurable) which is the AI agent server handling skills, chat, and automations; nginx (Ingress proxy) on port 48099 (fixed) which serves the landing page inside Home Assistant; and ttyd (Web terminal) on port 7681 (configurable) which provides a browser-based terminal for management.

**Data Persistence**

Everything under /config/ survives add-on updates. /config/.openclaw/ contains core config (openclaw.json), skills, and agent data. /config/clawd/ contains the agent workspace and custom skills. /config/secrets/ stores API tokens (HA token, provider keys). /config/keys/ stores SSH keys. /config/.linuxbrew/ contains Homebrew-installed CLI tools. The container filesystem (/usr/, /opt/) rebuilds with each image update, but your data and configuration persist.

**Communication Flow**

When you say "dim the bedroom lights to 30%," OpenClaw: 1) Understands the intent via its AI model, 2) Maps "bedroom lights" to the correct entity ID (e.g., light.bedroom_main), 3) Calls the HA REST API with the appropriate brightness value, 4) Confirms the action back to you.

Using OpenClaw as a Voice Assistant with Assist

One of the most compelling uses is replacing the default conversation agent in Home Assistant's Assist pipeline with OpenClaw.

**Why This Matters**

Home Assistant's built-in conversation agent handles simple commands well ("turn on the kitchen light") but struggles with multi-step commands ("turn off everything except the bedroom"), context from previous commands ("make it brighter" — brighter than what?), questions about state ("which lights are currently on?"), and conditional logic ("if the temperature drops below 18, turn on the heater"). OpenClaw handles all of these because it has persistent memory and multi-step reasoning.

**Setting Up Voice Satellites**

If you have ESP32-based voice satellites (like the popular M5Stack ATOM Echo), they work seamlessly. Flash the satellite with ESPHome voice assistant firmware. In HA, assign it to the OpenClaw-powered Assist pipeline. Say your wake word, then speak naturally. The satellite captures audio, HA transcribes it, OpenClaw processes the intent, HA executes the action, and the response is spoken back.

Performance and Resource Usage

Running OpenClaw inside Home Assistant adds overhead. Here's what to expect.

**Resource Consumption**

On a Raspberry Pi 4 (4GB), expect about 800MB RAM usage with moderate CPU impact — it works but is tight, so close the web terminal when not needed. On a Raspberry Pi 5 (8GB), RAM usage is about 800MB with low CPU impact — comfortable and the recommended minimum for Pi. On an Intel NUC or x86 system, RAM usage drops to about 600MB with negligible CPU impact — this is the ideal setup. On a Proxmox VM (4GB+), expect about 600MB RAM with negligible CPU impact — allocate at least 4GB to the VM.

**Latency**

Response times depend on your AI provider. Claude 3.5 Sonnet takes 1-3 seconds at about $0.003/command. GPT-4o takes 1-2 seconds at about $0.002/command. Local Ollama with Llama 3.1 8B takes 2-8 seconds on Pi 5 or 0.5-2 seconds on x86, at $0/command. For time-critical automations (like security alerts), consider using a cheaper, faster model for simple commands and reserving the premium model for complex reasoning.

Advanced: Webhook-Based Automations

For the most seamless integration, use Home Assistant webhooks to trigger OpenClaw actions.

**HA → OpenClaw (Events Trigger AI)**

Create a Home Assistant automation that notifies OpenClaw when something happens.

**OpenClaw → HA (AI Triggers Actions)**

OpenClaw can also trigger Home Assistant webhooks, with a corresponding HA automation to handle the action.

# automations.yaml
- alias: "Notify OpenClaw of doorbell"
  trigger:
    - platform: state
      entity_id: binary_sensor.doorbell
      to: "on"
  action:
    - service: rest_command.notify_openclaw
      data:
        message: "The doorbell just rang. Check the front door camera and let me know who it is."

# configuration.yaml
rest_command:
  notify_openclaw:
    url: "http://localhost:18789/api/v1/chat"
    method: POST
    headers:
      Authorization: "Bearer YOUR_GATEWAY_TOKEN"
      Content-Type: "application/json"
    payload: '{"message": "{{ message }}"}'

# From within an OpenClaw skill or automation
curl -X POST "http://localhost:8123/api/webhook/openclaw_action" \
  -H "Content-Type: application/json" \
  -d '{"action": "movie_mode", "room": "living_room"}'

- alias: "OpenClaw Movie Mode"
  trigger:
    - platform: webhook
      webhook_id: openclaw_action
  condition:
    - condition: template
      value_template: "{{ trigger.json.action == 'movie_mode' }}"
  action:
    - service: scene.turn_on
      target:
        entity_id: scene.living_room_movie
    - service: media_player.turn_on
      target:
        entity_id: media_player.living_room_tv

Troubleshooting Common Issues

**Add-on Won't Start**

Symptom: Add-on shows "Starting" indefinitely or crashes immediately. Fixes: Check the add-on log tab for error messages. Ensure you have enough free RAM (free -h in the HA terminal). Try stopping other resource-heavy add-ons temporarily. On Raspberry Pi, ensure you're using a good-quality power supply (at least 5V/3A).

**Gateway Not Accessible**

Symptom: "Open Gateway Web UI" button leads to a blank page or connection refused. Fixes: Verify the gateway is running with openclaw gateway status in the terminal. Check if the port is blocked by a firewall. If using lan_https, make sure the CA certificate is installed on your device. Try SSH port forwarding as a test.

**"Secure Context Required" Error**

Symptom: Web UI shows a security error about requiring HTTPS. Fixes: Set access_mode to lan_https (recommended). Or use SSH forwarding to access via localhost. Or set up a reverse proxy with HTTPS termination.

**OpenClaw Can't Reach Home Assistant API**

Symptom: API calls return connection refused or unauthorized errors. Fixes: Verify your Long-Lived Access Token hasn't expired. Test the connection manually. If you see {"message": "API running."}, the connection works — check your entity IDs. If connection refused, ensure the api integration is enabled in HA.

**High Memory Usage on Raspberry Pi**

Symptom: System becomes sluggish after installing the add-on. Fixes: Use a local model with smaller footprint or a cloud API instead of running Ollama on the Pi. Close the web terminal when not actively using it. Reduce the number of concurrent add-ons. Upgrade to a Raspberry Pi 5 with 8GB RAM or consider a cheap VPS for OpenClaw.

**Assist Pipeline Not Showing OpenClaw**

Symptom: OpenClaw doesn't appear as a conversation agent option. Fixes: Ensure the add-on is running and the gateway is accessible. Restart Home Assistant (not just the add-on). Check that the OpenAI-compatible API endpoint is exposed by the add-on. Verify in the add-on configuration that the Assist pipeline integration is enabled.

curl -s -H "Authorization: Bearer $(cat /config/secrets/homeassistant.token)" \
  http://localhost:8123/api/ | jq

Conclusion

Once you've got OpenClaw running inside Home Assistant, explore these next steps: Build custom skills for your specific smart home setup. Set up cron automations for scheduled smart home tasks. Connect messaging channels to control your home remotely via Telegram or Discord. Optimize costs to keep your AI bill low. Explore automation ideas for inspiration. The combination of Home Assistant's device ecosystem and OpenClaw's AI reasoning creates something genuinely new — a smart home that doesn't just follow rules, but understands context, learns from you, and adapts over time. That's the difference between automation and intelligence.

Frequently asked questions