How to Connect OpenClaw to Home Assistant: Complete Smart Home AI Agent Guide

Why Connect OpenClaw to Home Assistant?

Home Assistant is already the gold standard for self-hosted smart home control — over 2.5 million active installations as of early 2026. But its built-in voice assistant, Assist, is limited to predefined commands. You can say "turn on the kitchen lights," but you can't say "analyze why my hallway motion sensor keeps triggering false alarms at 3 AM and fix it."

OpenClaw bridges that gap. Here's what the integration enables:

Voice commands: Home Assistant alone supports predefined phrases only, while Home Assistant + OpenClaw supports natural language, any phrasing. Automation creation: Home Assistant alone requires manual YAML/UI editing, while OpenClaw lets you say "Make the porch light turn on at sunset." Troubleshooting: Home Assistant alone requires reading logs manually, while OpenClaw lets you ask "Why did my thermostat turn off last night?" Dashboard creation: Home Assistant alone uses a drag-and-drop UI builder, while OpenClaw lets you say "Build me a security dashboard with all cameras." Cross-platform messaging: Home Assistant alone is limited to the HA Companion App, while OpenClaw adds Telegram, Discord, WhatsApp, and SMS. Persistent memory: Home Assistant alone has none, while OpenClaw remembers preferences, past issues, and context. Proactive monitoring: Home Assistant alone relies on automation-based alerts, while OpenClaw's AI notices patterns and suggests improvements. Scheduled tasks: Home Assistant alone uses HA automations, while OpenClaw adds cron jobs, heartbeat checks, and email digests.

The key difference: OpenClaw doesn't just respond to commands. It understands context, remembers history, and takes initiative. It's the difference between a light switch and a smart butler.

Prerequisites

Before you start, make sure you have:

• **Home Assistant 2024.6 or later** (for LLM agent support)
• **Home Assistant OS (HAOS)** or a **Supervised installation** (required for add-ons)
• **An API key** from at least one LLM provider (Anthropic Claude recommended, but OpenAI and Google Gemini also work)
• **A messaging channel** set up: Telegram, Discord, or WhatsApp
• **Basic familiarity** with Home Assistant's Settings panel

Method 1: Install the OpenClaw Home Assistant Add-on (Easiest)

The community-maintained OpenClaw Assistant add-on is the fastest path. It runs OpenClaw directly inside Home Assistant OS — no separate server needed.

**Step 1: Add the Repository** In Home Assistant, go to Settings, Add-ons, Add-on Store. Click the three dots menu in the top right. Select Repositories. Paste the repository URL, click Add, then Close. Refresh the page — you should see "OpenClaw Assistant" in the store.

**Step 2: Install and Configure** Click OpenClaw Assistant, then Install. Wait for the installation to complete (this downloads ~1.5 GB of dependencies including Chromium, Node.js, and bundled tools). Go to the Configuration tab and set your options:

**Step 3: Verify the Installation** Once the add-on starts, open the Log tab. You should see the gateway started on port 18789, agent initialized successfully, connected to Home Assistant via ha-mcp, and Telegram channel connected. You can also access the web terminal by clicking Open Web UI in the add-on panel.

**Supported Architectures** The add-on supports all major Home Assistant platforms: amd64 (Intel/AMD x86_64), aarch64 (Raspberry Pi 4/5, Apple Silicon), and armv7 (Raspberry Pi 3, older ARM devices).

https://github.com/techartdev/OpenClawHomeAssistant

# Minimum required configuration
anthropic_api_key: "sk-ant-your-key-here"

# Optional: messaging channel
telegram_bot_token: "123456:ABC-DEF..."
telegram_chat_id: "your-chat-id"

# Optional: for local model fallback
ollama_url: "http://homeassistant.local:11434"

[openclaw] Gateway started on port 18789
[openclaw] Agent initialized successfully
[openclaw] Connected to Home Assistant via ha-mcp
[openclaw] Telegram channel connected

Method 2: Run OpenClaw on a Separate Server with ha-mcp

If you prefer keeping OpenClaw on its own machine (better resource isolation, more flexibility), you can connect it to Home Assistant using the ha-mcp (Model Context Protocol) server.

This is the approach many power users prefer — especially those running OpenClaw on a VPS or Proxmox.

**Step 1: Generate a Long-Lived Access Token in Home Assistant** In Home Assistant, click your profile icon (bottom-left). Scroll to Long-Lived Access Tokens. Click Create Token. Name it "OpenClaw" and copy the token immediately (it won't be shown again).

**Step 2: Install ha-mcp on Your Home Assistant Instance** The MCP server exposes Home Assistant's API in a format that LLM agents can understand.

After restarting, go to Settings, Devices & Services, Add Integration and search for "MCP Server." Configure it with default settings.

**Step 3: Configure OpenClaw to Connect** On your OpenClaw server, add the MCP connection to your skill configuration:

Add your Home Assistant credentials to the environment:

**Step 4: Test the Connection** Send a message to your OpenClaw agent via Telegram (or your preferred channel): "What devices does Home Assistant see right now?" If everything is connected, your agent should respond with a list of your entities, their states, and available controls.

# SSH into your Home Assistant machine or use the Terminal add-on
# Install ha-mcp as a Home Assistant custom component

# Option A: HACS (recommended)
# 1. Open HACS in Home Assistant
# 2. Search for "ha-mcp" or "Home Assistant MCP"
# 3. Install and restart Home Assistant

# Option B: Manual installation
cd /config/custom_components
git clone https://github.com/homeassistant-ai/ha-mcp.git mcp_server
# Restart Home Assistant

# SSH into your OpenClaw server
cd /root/clawd

# Add the Home Assistant MCP skill configuration
cat >> skills/home-assistant/SKILL.md << 'EOF'
# Home Assistant Integration

## MCP Connection
- Server: http://homeassistant.local:8123
- Token: (stored in .env)
- Protocol: ha-mcp v2

## Capabilities
- Control all entities (lights, switches, climate, covers, media)
- Read sensor data and history
- Create and modify automations
- Manage scenes and scripts
- Access logbook and error logs
EOF

# Add to your OpenClaw .env file
echo 'HA_URL=http://homeassistant.local:8123' >> .env
echo 'HA_TOKEN=your-long-lived-access-token' >> .env

# Restart OpenClaw
openclaw gateway restart

Setting Up Voice Control

One of the most compelling features of an OpenClaw + Home Assistant setup is voice control that actually understands context. Here's how to set it up.

**Option A: Use OpenClaw as an Assist Conversation Agent** The OpenClaw add-on exposes an OpenAI-compatible API that Home Assistant's Assist pipeline can use: Go to Settings, Voice Assistants. Click Add Assistant. Set the Conversation Agent to "OpenClaw Assistant." Configure the Speech-to-Text engine (Whisper recommended for local processing). Configure the Text-to-Speech engine (choose from Piper, Google Cloud TTS, or ElevenLabs). Now when you use Assist (via the companion app, a voice satellite, or an ESPHome device), your commands go through OpenClaw instead of the basic Assist NLP.

**Option B: ElevenLabs Voice via Telegram** If you want your agent to speak back to you with a natural voice via Telegram: Get an ElevenLabs API key from elevenlabs.io. Add it to your OpenClaw configuration. In your agent's TOOLS.md, set a preferred voice. Now you can ask your agent to respond with voice, for example: "Send me a voice summary of today's energy usage."

**Option C: Full Duplex Voice with ESPHome Satellites** For the ultimate hands-free experience, combine ESPHome voice satellites with OpenClaw: Build or buy an ESPHome voice satellite (ESP32-S3 with microphone and speaker). Configure the satellite's Assist pipeline to use OpenClaw as the conversation agent. Place satellites around your home — kitchen, bedroom, office. The result: say "Hey Jarvis, why is the living room so cold?" and get an intelligent response like "Your living room thermostat is set to 18 degrees C, but the window sensor shows the bedroom window has been open for 2 hours. Want me to close the blinds and bump the heat to 21 degrees C?"

echo 'ELEVENLABS_API_KEY=your-key-here' >> .env

### TTS
- Preferred voice: "Lily" (warm, theatrical)
- Default output: Telegram voice message

10 Powerful Things You Can Do with OpenClaw + Home Assistant

**1. Create Automations with Plain English** Tell your agent something like "When I leave the house, turn off all lights, lock the front door, and set the thermostat to eco mode." The agent creates an automation triggered by your phone's device_tracker changing to 'not_home', turning off all lights, locking the front door, and setting the thermostat to eco preset — then asks if you want to activate it.

**2. Diagnose Problems from Logs** Ask "My Zigbee network has been flaky this week. What's going on?" and the agent checks Home Assistant logs for the last 7 days, finding 47 "device unavailable" events, clustering between 18:00-20:00 in the kitchen/dining area, with your WiFi AP on channel 1 overlapping Zigbee channel 15. It then recommends changing your Zigbee coordinator to channel 20 or moving your WiFi AP to channel 6 or 11.

**3. Morning Briefings via Telegram** Set up a cron job to send you a daily briefing at 7:00 AM with today's weather forecast, calendar events, overnight security events, energy usage vs. yesterday, and any devices that went offline.

**4. Energy Monitoring and Optimization** Ask "How much electricity did I use this month compared to last month?" and get a detailed breakdown with savings analysis.

**5. Security Monitoring with Context** The agent can send proactive alerts via Telegram at 2:30 AM when motion is detected on the front porch camera, checking context like whether anyone is expected to be out, temperature, motion patterns, door lock status, and automatically turning on flood lights.

**6. Guest Mode Setup** Tell the agent "My parents are visiting this weekend. Set up guest mode" and it activates a guest scene — adding guest bedroom lights to automations, adjusting thermostat (remembering your parents like it warm from last visit), scheduling the coffee machine, disabling loud music automations, and sharing the WiFi guest password.

**7. Adaptive Lighting Schedules** Say "Make the lights gradually dim in the evening to help me sleep better" and the agent creates a circadian lighting automation that shifts color temperature and brightness from 18:00 through 23:00.

**8. Appliance Monitoring** Say "Tell me when the washing machine is done" and the agent monitors the smart plug's power consumption, sending a Telegram notification when the cycle finishes with usage stats.

**9. Multi-Room Audio Control** Say "Play some jazz in the living room and kitchen, keep it low" and the agent plays a Jazz Classics playlist on grouped speakers at appropriate volumes.

**10. Vacation Mode with Presence Simulation** Tell the agent you're leaving for vacation and it configures randomized light patterns, TV schedules, blind automation, mail forwarding, water leak sensor alerts, frost protection thermostat settings, and daily security summaries.

Architecture Overview

Here's how the components connect: Your devices (Telegram, Discord, WhatsApp) send messages to the OpenClaw Gateway (port 18789), which contains the LLM Engine (Claude/GPT/Gemini), Memory System (SOUL, MEMORY, daily), and Skills Engine. The gateway connects to ha-mcp (HA API) and other services (Email, Calendar, Browser, etc.). ha-mcp communicates with Home Assistant (port 8123), which manages your Zigbee, Z-Wave, WiFi, and Matter/Thread devices. These in turn control your physical devices: lights, thermostats, locks, cameras, plugs, blinds, and speakers.

┌─────────────────────────────────────────────────────────┐
│  Your Devices                                           │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│  │ Telegram  │  │ Discord  │  │ WhatsApp │              │
│  │   App     │  │   App    │  │   App    │              │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘              │
│       └──────────────┼──────────────┘                   │
│                      ▼                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │  OpenClaw Gateway (port 18789)                  │    │
│  │  ┌─────────────┐  ┌──────────┐  ┌───────────┐  │    │
│  │  │ LLM Engine  │  │ Memory   │  │ Skills    │  │    │
│  │  │ (Claude/    │  │ System   │  │ Engine    │  │    │
│  │  │  GPT/Gemini)│  │ (SOUL,   │  │           │  │    │
│  │  │             │  │  MEMORY, │  │           │  │    │
│  │  │             │  │  daily)  │  │           │  │    │
│  │  └─────────────┘  └──────────┘  └───────────┘  │    │
│  │                      │                          │    │
│  │              ┌───────┴────────┐                  │    │
│  │              ▼                ▼                  │    │
│  │  ┌──────────────┐  ┌──────────────────┐         │    │
│  │  │  ha-mcp      │  │  Other Services  │         │    │
│  │  │  (HA API)    │  │  (Email, Cal,    │         │    │
│  │  │              │  │   Browser, etc.) │         │    │
│  │  └──────┬───────┘  └──────────────────┘         │    │
│  └─────────┼───────────────────────────────────────┘    │
│            ▼                                            │
│  ┌─────────────────────────────────────────────────┐    │
│  │  Home Assistant (port 8123)                     │    │
│  │  ┌──────┐ ┌───────┐ ┌────────┐ ┌────────────┐  │    │
│  │  │Zigbee│ │Z-Wave │ │  WiFi  │ │   Matter   │  │    │
│  │  │      │ │       │ │Devices │ │  /Thread    │  │    │
│  │  └──────┘ └───────┘ └────────┘ └────────────┘  │    │
│  └─────────────────────────────────────────────────┘    │
│            ▼                                            │
│  ┌─────────────────────────────────────────────────┐    │
│  │  Physical Devices                               │    │
│  │  Lights  Thermostats  Locks  Cameras             │    │
│  │  Plugs   Blinds       Speakers                   │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Choosing the Right AI Model for Smart Home Control

Not all models are equal for home automation tasks. Here's how they compare:

Claude 3.5 Sonnet has ~1.5s latency, excellent tool calling, 200K context window, costs $15-30/month, and is the best all-rounder for HA. Claude Opus 4 has ~3s latency, excellent tool calling, 200K context, costs $40-80/month, best for complex diagnostics. GPT-4o has ~1.2s latency, excellent tool calling, 128K context, costs $20-40/month, best for fast responses. GPT-4o Mini has ~0.8s latency, good tool calling, 128K context, costs $3-8/month, best as a budget-friendly option. Gemini 2.0 Flash has ~0.6s latency, good tool calling, 1M context, costs $5-15/month, best for huge context and fast speed. Llama 3.3 70B (local) has ~2-5s latency, moderate tool calling, 128K context, costs $0/month (hardware only), best for privacy-focused setups.

For most Home Assistant users, Claude 3.5 Sonnet offers the best balance of intelligence, tool-calling reliability, and cost. If you want to run models locally for free, Llama 3.3 via Ollama works well for basic commands but struggles with complex multi-step automations.

Troubleshooting Common Issues

**Issue 1: "Cannot connect to Home Assistant"** Symptoms: OpenClaw starts but can't reach Home Assistant's API. Common fix: Use IP address instead of hostname. Check firewall settings.

**Issue 2: "Entity not found" Errors** Symptoms: OpenClaw tries to control a device but gets entity ID wrong. Make sure ha-mcp is exposing the correct entities. Check entity IDs in Home Assistant: Settings, Devices & Services, Entities. Add entity aliases in your agent's TOOLS.md.

**Issue 3: Slow Response Times** Symptoms: Commands take 5-10+ seconds to execute. Common causes and solutions: Large entity list — filter exposed entities in ha-mcp settings. Cloud API latency — use a faster model (GPT-4o Mini, Gemini Flash). Raspberry Pi bottleneck — allocate more RAM, use NVMe storage. Network issues — use wired Ethernet, not WiFi. Too many skills loaded — disable unused OpenClaw skills.

**Issue 4: Add-on Won't Start** Symptoms: Add-on shows "Starting" indefinitely or crashes immediately. Common causes: Invalid API key, port conflict (another service using port 18789), insufficient RAM (allocate at least 2GB), or corrupted install (uninstall, remove repository, re-add, reinstall).

**Issue 5: Automations Created by OpenClaw Don't Fire** Symptoms: The agent says it created an automation, but nothing happens. Check Settings, Automations to verify it was actually created. Look at the automation's YAML — the agent might have used incorrect trigger syntax. Run the automation manually to test. Check the automation trace to see where it fails. Tell OpenClaw about the failure — it can often self-correct.

# Check if Home Assistant is reachable
curl -s -H "Authorization: Bearer YOUR_TOKEN" \
  http://homeassistant.local:8123/api/ | jq .

# If using the add-on, the internal URL is different:
curl -s -H "Authorization: Bearer $SUPERVISOR_TOKEN" \
  http://supervisor/core/api/ | jq .

# Common fix: Use IP address instead of hostname
# Replace homeassistant.local with 192.168.1.x

# Check firewall
sudo ufw status
sudo ufw allow from 192.168.1.0/24 to any port 8123

### Home Assistant Entity Aliases
- "living room lights" → light.living_room_main, light.living_room_accent
- "front door" → lock.front_door_lock, binary_sensor.front_door_contact
- "thermostat" → climate.nest_thermostat

# Check add-on logs
ha addons logs openclaw_assistant

# Common causes:
# 1. Invalid API key → double-check your anthropic_api_key
# 2. Port conflict → another service using port 18789
# 3. Insufficient RAM → allocate at least 2GB to the add-on
# 4. Corrupted install → uninstall, remove repository, re-add, reinstall

Security Considerations

Running an AI agent with access to your smart home requires careful security practices:

• **Use a dedicated API token** for OpenClaw — don't reuse your admin token
• **Limit exposed entities** in ha-mcp — only expose what the agent needs
• **Set up confirmation for critical actions** — locks, garage doors, alarm systems should require explicit approval
• **Run OpenClaw behind Tailscale** for zero-trust networking
• **Review the add-on's security documentation** before deploying
• **Keep both Home Assistant and OpenClaw updated** — security patches matter
• **Monitor the agent's actions** — check daily logs in memory/YYYY-MM-DD.md

Cost Breakdown

What does this actually cost to run monthly?

Home Assistant is free (open-source software). OpenClaw is free (self-hosted, open-source). Claude API (Sonnet) costs $15-30/month for ~500-1000 commands/day. Claude API (Opus) costs $40-80/month for heavy users. GPT-4o Mini costs $3-8/month as a budget option. Ollama (local) costs $0/month but requires capable hardware. ElevenLabs TTS costs $0-5/month (free tier covers basic use). Telegram is free. Hardware (amortized) costs $5-15/month for a Raspberry Pi or VPS. Total for a budget setup: $3-15/month with a local model and Pi. Total for a recommended setup: $20-45/month with Claude Sonnet and cloud.

Conclusion

Once you have OpenClaw connected to Home Assistant, the possibilities expand rapidly: write custom skills for your specific home setup, set up heartbeat monitoring to catch issues before they become problems, add email integration so your agent can send you daily home reports, and explore the 240+ star GitHub repository for the HA add-on. The combination of a persistent AI agent and a comprehensive smart home platform is genuinely transformative. It's not just about voice commands or automations — it's about having a system that understands your home, remembers your preferences, and gets smarter over time. Start with simple commands. Let the agent learn your patterns. Before long, you'll wonder how you ever managed your smart home without it.

Frequently asked questions