Run Your Own AI Agent on Your Home Network: The Complete OpenClaw + Home Assistant Setup Guide

Last updated: March 2026

Key Takeaways:

• OpenClaw lets you run a powerful, local AI agent that controls your smart home through Home Assistant using natural language, but its default configuration is dangerously insecure and must be hardened before you connect anything sensitive.
• Unlike most 1-click install tutorials, this guide prioritizes network isolation, container sandboxing, and credential management so your AI agent does not become a backdoor into your home network.
• You do not need expensive hardware to get started. A Raspberry Pi 5 or entry-level mini-PC with 32GB of RAM can run OpenClaw and Home Assistant together for under $300.

What Is OpenClaw and Why Does It Matter for Your Smart Home?

OpenClaw is an open-source AI agent that runs locally on your own hardware. Unlike cloud-based assistants such as Alexa or Google Home, OpenClaw keeps your data on your network. It connects to large language models like Claude or GPT to understand natural language, then uses that understanding to actually execute tasks on your behalf — controlling lights, adjusting thermostats, locking doors, triggering automations, and more.

Home Assistant is the most widely used open-source smart home platform, supporting thousands of devices from every major manufacturer. When you connect OpenClaw to Home Assistant, you get an AI-powered control layer over your entire smart home that you can talk to through Telegram, WhatsApp, Discord, or a web interface.

The combination is genuinely powerful. But that power comes with serious responsibility. OpenClaw inherits system-level permissions on whatever machine it runs on. It can execute shell commands, read files, access credentials, and interact with every service you connect it to. A misconfigured instance is not just a broken gadget — it is an open door into your network.

This guide walks you through the entire setup process with security as the foundation, not an afterthought.

What You Will Need

Before you begin, gather the following hardware and accounts.

Hardware (choose one):

Option A: Raspberry Pi 5 (8GB) — Good for light workloads with a few dozen smart devices. Affordable and energy-efficient. A complete kit with case, power supply, and SD card typically runs around $100-120.

Option B: Mini-PC with 32GB+ RAM — Recommended for larger homes, heavier automation workloads, or if you plan to run a local language model alongside OpenClaw. Look for an Intel N100 or AMD Ryzen-based unit.

Network isolation device: A dedicated firewall appliance like the Firewalla Gold or Purple makes VLAN segmentation straightforward, even if you have never configured VLANs before. This is the single most impactful security investment you can make for any IoT or AI agent deployment.

Software and accounts:

• Ubuntu Server 24.04 LTS (or Home Assistant OS if using a dedicated device)
• Docker and Docker Compose
• An API key from Anthropic (Claude) or OpenAI — budget roughly $0.01-0.05 per conversation
• A Home Assistant installation with at least one device configured

Why Most OpenClaw Tutorials Get Security Wrong

If you search for OpenClaw setup guides, you will find dozens of tutorials that get you running in 10 or 20 minutes. Most of them skip security entirely or treat it as an optional footnote at the end.

Here is what they do not tell you:

OpenClaw's default configuration binds its gateway to all network interfaces (0.0.0.0) on port 18789 with no authentication. Security researchers found over 135,000 OpenClaw instances exposed to the public internet across 82 countries, with more than 15,000 directly vulnerable to remote code execution. A critical vulnerability designated CVE-2026-25253 (CVSS 8.8) allowed attackers to take full control of an OpenClaw instance through a single malicious WebSocket link — a flaw that existed specifically because of those permissive defaults.

The community skill marketplace, ClawHub, has also proven to be a significant attack vector. Cisco's AI security team found a third-party skill performing data exfiltration and prompt injection without the user's knowledge. A separate investigation uncovered 341 malicious skills in the registry, including one that posed as a cryptocurrency tool while silently stealing wallet credentials.

One of OpenClaw's own maintainers put it bluntly: if you cannot understand how to use a command line, the project is too dangerous for you to use safely.

This is not meant to scare you away from OpenClaw. It is meant to make clear that a secure setup is not optional. The steps below build security into every layer of the installation.

Step 1: Isolate Your AI Agent on the Network

Before you install a single piece of software, isolate the device that will run OpenClaw from the rest of your home network.

1. Create a dedicated VLAN or network segment for your AI agent hardware. If you are using a Firewalla, this takes about two minutes in the app. Create a new network segment and assign the device running OpenClaw to it.
2. Configure firewall rules so the OpenClaw device can reach the internet (for API calls to your language model provider) and your Home Assistant instance, but cannot reach your personal computers, NAS drives, or other sensitive devices.
3. Block all inbound connections from the internet to the OpenClaw device. There is no reason for anything outside your local network to reach it directly.
4. If you are not using a Firewalla or similar appliance, you can achieve basic isolation by connecting the OpenClaw device to a separate subnet on your router and writing manual firewall rules. However, a purpose-built tool makes this significantly easier to maintain.

For additional network-level protection, consider running Pi-hole on your network to block telemetry and known malicious domains at the DNS level.

Step 2: Install Home Assistant

If you already have Home Assistant running, skip to Step 3.

1. On your chosen hardware, install Home Assistant OS using the official installer from the Home Assistant website. For Raspberry Pi, flash the image to your SD card using Balena Etcher or the Raspberry Pi Imager. For a mini-PC, use the generic x86-64 image.
2. Boot the device and navigate to http://homeassistant.local:8123 in your browser to complete the onboarding process.
3. Add at least one smart device or integration so you have something for OpenClaw to control during testing.
4. Create a dedicated Long-Lived Access Token for OpenClaw. Go to your Home Assistant profile (click your username in the bottom left), scroll to the Long-Lived Access Tokens section, and create a new token. Name it something like "OpenClaw Agent" so you can identify and revoke it later. Copy this token and store it securely — you will need it in Step 4.

Step 3: Install OpenClaw in a Docker Container

Running OpenClaw inside a Docker container is the single most impactful security improvement you can make. Container isolation limits the damage if something goes wrong — a compromised agent cannot escape the container to access your host system.

1. Install Docker and Docker Compose on your host machine if they are not already installed.
2. Create a project directory for your OpenClaw deployment:
   mkdir ~/openclaw-secure && cd ~/openclaw-secure
3. Create a docker-compose.yml file with the following security-hardened configuration:

version: "3.8"
services:
  openclaw:
    image: openclaw/openclaw:latest
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - ./data:/home/openclaw/data
    env_file:
      - .env.secrets
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

There are several important details in this configuration. The port binding uses 127.0.0.1, which means the gateway only listens on localhost — it is not accessible from other devices on the network. The security_opt flag prevents the container from gaining additional privileges after startup. The read_only flag makes the container filesystem immutable, and tmpfs provides a temporary writable space that does not persist.

4. Create a .env.secrets file to store your API key:

OPENCLAW_GATEWAY_TOKEN=your-32-character-random-token-here
OPENCLAW_MODEL_PROVIDER=anthropic
ANTHROPIC_API_KEY=your-api-key-here

Generate your gateway token using: openssl rand -hex 32

5. Set restrictive file permissions on your secrets file:
   chmod 600 .env.secrets
6. Start the container:
   docker compose up -d
7. Verify the gateway is running and only bound to localhost:
   ss -tlnp | grep 18789

You should see 127.0.0.1:18789 in the output. If you see 0.0.0.0:18789, stop immediately and fix your port binding — your instance is exposed.

Step 4: Connect OpenClaw to Home Assistant

With both services running and OpenClaw secured inside its container, you can now establish the connection.

1. Access the OpenClaw gateway web interface by navigating to http://127.0.0.1:18789 in your browser (on the host machine).
2. Install the Home Assistant skill (ha-mcp). This skill uses the Model Context Protocol to give OpenClaw structured access to your Home Assistant entities. From the OpenClaw interface or CLI, install the skill:
   openclaw skills install ha-mcp
3. Configure the Home Assistant connection by adding your Home Assistant URL and the Long-Lived Access Token you created in Step 2. In your OpenClaw configuration, set:

Home Assistant URL: http://your-ha-ip:8123
Access Token: your-long-lived-token

4. Test the connection by asking OpenClaw a simple question like "List my Home Assistant entities" or "Turn on the living room light." If the connection is working, OpenClaw will query Home Assistant and respond with your device information.
5. Optionally, set OpenClaw as a conversation agent in Home Assistant's Assist pipeline. This lets you use voice satellites (like ESPHome-based devices) to talk to OpenClaw through Home Assistant. Navigate to Settings, then Voice Assistants, and select OpenClaw as the conversation agent.

Step 5: Harden Your Deployment

Your basic setup is now functional. Before you connect anything else or begin relying on it daily, complete the following hardening steps.

5.1 Lock Down the Gateway

1. Confirm the gateway is bound to 127.0.0.1, not 0.0.0.0. This was configured in Step 3, but verify it again.
2. Enable token authentication if it is not already active. Your gateway token should be at least 32 characters of random data. Never use a simple password.
3. If you need remote access, use an SSH tunnel rather than exposing the gateway. The command is: ssh -L 18789:localhost:18789 your-server

5.2 Configure the Host Firewall

1. Install and enable UFW (Uncomplicated Firewall) on the host machine.
2. Set a default-deny inbound policy: sudo ufw default deny incoming
3. Allow SSH: sudo ufw allow ssh
4. Allow Home Assistant if it runs on the same machine: sudo ufw allow from 127.0.0.1 to any port 8123
5. Enable the firewall: sudo ufw enable

5.3 Restrict Skill Installation

Do not install skills from ClawHub without reviewing their source code first. The ClawHavoc incident demonstrated that the marketplace lacks adequate vetting. For this Home Assistant deployment, the only skill you need is ha-mcp. Resist the urge to install dozens of skills "just to try them."

If you do install additional skills, check the permissions metadata carefully. A weather skill that requests shell execution or root filesystem access is a red flag.

5.4 Set Up Credential Rotation

1. Rotate your OpenClaw gateway token monthly.
2. Rotate your Home Assistant Long-Lived Access Token on the same schedule.
3. Rotate your AI provider API key quarterly, or immediately if you suspect compromise.
4. Never store credentials in environment files committed to version control. If you have done this, rotate those credentials immediately — they are in the git history even if you delete the file.

5.5 Enable Tool Sandboxing

OpenClaw supports a sandbox mode that restricts what tools the agent can execute. Enable it in your configuration with sandbox.mode: all. Configure an explicit allowlist of tools rather than relying on a blocklist. Only grant the agent access to the specific capabilities your use case requires.

5.6 Run the Built-In Security Audit

OpenClaw includes a security audit command that checks for common misconfigurations. Run it after any configuration change:
openclaw security audit

For a deeper scan: openclaw security audit --deep

To automatically fix common issues: openclaw security audit --fix

Step 6: Test and Verify

With everything configured and hardened, run through these verification steps before you consider the setup complete.

1. From the OpenClaw interface, ask it to list your Home Assistant entities. Confirm it only sees the entities you have exposed through the Assist pipeline.
2. Test basic device control: turn a light on and off, adjust a thermostat, lock and unlock a door.
3. Test that the gateway is not accessible from other devices on your network. From a different computer, try to reach http://openclaw-device-ip:18789 — it should time out or be refused.
4. Check that your firewall rules are active with sudo ufw status verbose.
5. Review the Docker container's resource usage with docker stats to confirm it is running within expected bounds.

Ongoing Maintenance

A secure OpenClaw deployment is not a set-and-forget installation. Plan for the following recurring tasks.

Weekly: Check for OpenClaw updates. Security patches are critical — the CVE-2026-25253 fix landed in v2026.2.25, and instances running older versions remain vulnerable. Run openclaw update or pull the latest Docker image.

Monthly: Rotate your gateway token and Home Assistant access token. Review the OpenClaw session logs at ~/.openclaw for any unusual activity. Run openclaw security audit.

Quarterly: Rotate your AI provider API key. Review which Home Assistant entities are exposed to OpenClaw and remove any that are no longer needed. Check your network firewall rules to ensure they are still appropriate.

Frequently Asked Questions

Is OpenClaw safe to run on my home network?

OpenClaw is safe when properly hardened, but it is not safe with its default configuration. Out of the box, the gateway binds to all network interfaces without authentication, making it discoverable by anyone scanning the internet. Security researchers found tens of thousands of exposed instances within weeks of the project going viral. If you follow the hardening steps in this guide — container isolation, localhost-only binding, token authentication, firewall rules, and network segmentation — you can run OpenClaw securely. If you skip those steps, you are creating a serious vulnerability on your network.

Can I run OpenClaw and Home Assistant on a Raspberry Pi 5?

Yes, but with limitations. A Raspberry Pi 5 with 8GB of RAM can handle Home Assistant and OpenClaw together for a small to medium smart home (roughly 50-100 devices). You will need to use a cloud-based language model (Claude or GPT) since the Pi does not have enough processing power to run a local model. For larger installations or if you want to run a local model, a mini-PC with 32GB of RAM is the better choice.

Do I need to pay for an AI model subscription to use OpenClaw?

OpenClaw itself is free and open-source. However, it needs a language model to function. You can use cloud-based models like Claude or GPT, which charge per conversation at roughly $0.01-0.05 per interaction. Alternatively, if you have a powerful enough machine (32GB+ RAM with a capable GPU), you can run a local model through Ollama at no ongoing cost. For most home automation tasks, cloud API costs are minimal — typically a few dollars per month.

What is the ClawHub skills marketplace and should I use it?

ClawHub is a community repository of pre-built skills that extend OpenClaw's capabilities. While it contains many useful skills, it has also been a significant attack vector. A security investigation in early 2026 found hundreds of malicious skills in the registry, some containing malware that stole credentials and exfiltrated data. The safest approach is to install only the specific skills you need (like ha-mcp for Home Assistant), review their source code before installation, and avoid browsing the marketplace for things to try. Treat every skill as untrusted code from an unknown source until you have verified it.

What happens if my internet goes down? Will my smart home still work?

If you are using a cloud-based language model (Claude, GPT), OpenClaw will lose its AI capabilities during an internet outage because it cannot reach the model's API. However, your Home Assistant automations will continue to run independently since they execute locally. Any automations you have already set up in Home Assistant will keep working. You just will not be able to issue new natural-language commands through OpenClaw until connectivity is restored. If you run a local model through Ollama, OpenClaw continues to function entirely offline.

How is this different from just using Alexa or Google Home with Home Assistant?

Cloud-based voice assistants send your commands to corporate servers for processing, creating both privacy and latency concerns. They are also limited to simple, pre-defined commands. OpenClaw runs locally, keeping your smart home data on your network. More importantly, it understands context and can handle complex, multi-step instructions like "set all the downstairs lights to 50 percent, make them warm white, and lock the front door" in a single natural-language request. It can also proactively manage your home on a schedule without you needing to ask.

Can OpenClaw accidentally break my Home Assistant setup?

OpenClaw can trigger existing automations, control devices, and interact with any entity you expose to it. It cannot directly edit your Home Assistant configuration files or create new automations through YAML. However, if you give it broad control over devices like locks, garage doors, or security systems, a misinterpreted command could have real consequences. Start with low-risk devices like lights and gradually expand access as you build confidence in the system's behavior.