I Gave My Smart Home a Brain: OpenClaw AI Agent on Raspberry Pi 5 + Home Assistant (2026)
I Gave My Smart Home a Brain: OpenClaw AI Agent on Raspberry Pi 5 + Home Assistant (2026)
A complete, honest guide to setting up an always-on AI agent alongside HAOS — with every gotcha we hit along the way documented.
Before You Begin
Why Can't I Just Install OpenClaw Directly on the Pi?
Home Assistant OS (HAOS) is a locked-down, read-only operating system. Unlike regular Linux, you can't run apt install, npm, or any standard tooling directly on the host. The solution is to install OpenClaw as a HAOS Add-on — a Docker container managed by the Home Assistant Supervisor.
Direct npm/apt installs, systemd services, writing to most of the filesystem, and running arbitrary processes on the host OS.
Install OpenClaw as a HAOS Add-on — a Docker container that starts on boot, auto-restarts, and shows logs in the HA UI.
The 2026.2 update renamed Add-ons → Apps and moved them out of Settings into their own sidebar. Any older tutorial will have wrong navigation paths.
What You'll Need
| Item | Details | Where |
|---|---|---|
| Raspberry Pi 5 | 4GB or 8GB recommended | Your hardware |
| Home Assistant OS | 2026.2 or later | Already installed |
| Anthropic API Key | For Claude Sonnet — see below | console.anthropic.com |
| Telegram Bot Token | Created via @BotFather — see below | Telegram app |
| Your Telegram User ID | To lock the bot to only you | Message @userinfobot |
| SSH Add-on | "Advanced SSH & Terminal" in HA | HA App Store |
Sign up or log in and add a payment method. Claude Sonnet 4.6 costs roughly $3 per million input tokens — expect $2–10/month for a personal home assistant.
Go to API Keys → Create Key. Name it openclaw-pi. Copy it immediately — it's only shown once.
Your Anthropic key gives billing access. Never paste it into forums, commit it to git, or share it publicly. Revoke it immediately if accidentally exposed.
In the Console go to Settings → Limits and set a monthly cap — $20 is plenty for personal use.
Search for @BotFather (blue verified tick) and start a conversation.
/newbot # BotFather asks for a display name: My Home Assistant Bot # Then a username (must end in 'bot'): myhome_claw_bot
BotFather replies with your Bot Token — e.g. 8553574581:AAGgFKBc.... Save it securely.
Message @userinfobot on Telegram. It instantly replies with your numeric ID (e.g. 7699395479). Save this — you'll use it to lock the bot to only you.
In BotFather send /setuserpic and upload a photo. Makes it easy to find in your chat list. A lobster 🦞 works well.
Installation
In the left sidebar click Apps → App Store. If you see "Add-ons" instead of "Apps" you're on an older HA version — the path is the same.
Click the ⋮ menu (top right) → Repositories → paste this URL and click Add:
https://github.com/techartdev/OpenClawHomeAssistant
Scroll down in the App Store — OpenClaw Assistant should now appear.
Click OpenClaw Assistant → Install. This pulls the Docker image — 3–5 minutes on first run.
enable_terminal: true timezone: "Asia/Riyadh" # change to your timezone gateway_public_url: "" homeassistant_token: ""
On the Info tab enable Start on boot and Watchdog, then click Start.
Click Open Web UI on the add-on page — an embedded terminal opens inside Home Assistant.
root@openclaw:/# openclaw onboard
When the wizard asks, make these choices:
- Access mode — set to lan_https (switch to YAML view in the Configuration tab to edit this field — the visual editor does not expose it)
- AI provider — Anthropic → paste your API key
- Model — claude-sonnet-4-6
- Channel — Telegram → paste your Bot Token
- Skills prompt — skip for now (we install manually in Tab 4)
- Hatch mode — Hatch in TUI (recommended)
The default is "custom" which breaks local network access. This field is not exposed in the visual editor — you must switch to YAML view (toggle in the top-right of the Configuration tab), then manually set access_mode: lan_https. Without this your gateway UI will be unreachable on the local network.
After onboarding, OpenClaw launches its TUI and greets you — both in the terminal and on Telegram simultaneously:
Wake up, my friend! Hey. I just came online — fresh start, blank slate. I see a BOOTSTRAP.md waiting for me. So... who am I? Who are you? Let's figure that out together. 😄 connected | idle | tokens 8.6k/200k (4%)
Introduce yourself and give the agent a name and personality. This shapes how it behaves in every future session.
Inside the HAOS container, systemctl doesn't work. Always restart OpenClaw via Apps → OpenClaw Assistant → Restart in the HA UI. Running openclaw gateway restart will fail.
Security & Configuration
Run the Doctor First
Always run this after installation — it surfaces every misconfiguration in one pass.
root@openclaw:/# openclaw doctor
By default OpenClaw responds to anyone who messages your bot. Lock it down immediately:
root@openclaw:/# openclaw config set channels.telegram.dmPolicy pairing root@openclaw:/# openclaw config set channels.telegram.allowFrom '["YOUR_TELEGRAM_ID"]' # Replace with your numeric ID from @userinfobot root@openclaw:/# openclaw config set channels.telegram.groupPolicy open
Verify it took:
root@openclaw:/# openclaw config get channels.telegram { "dmPolicy": "pairing", "allowFrom": ["YOUR_ID_HERE"], "groupPolicy": "open", "streaming": "partial" }
root@openclaw:/# chmod 700 /config/.openclaw root@openclaw:/# mkdir -p /config/.openclaw/credentials
Reduces startup time and CPU overhead on the Pi 5. Will take effect after the next add-on restart.
root@openclaw:/# mkdir -p /var/tmp/openclaw-compile-cache root@openclaw:/# cat >> /etc/environment << 'EOF' NODE_COMPILE_CACHE=/var/tmp/openclaw-compile-cache OPENCLAW_NO_RESPAWN=1 EOF
Memory search requires an additional embedding API key (OpenAI, Gemini etc). If you're Anthropic-only, disable it. Reducing log level also extends SD card life on 24/7 operation.
root@openclaw:/# openclaw config set agents.defaults.memorySearch.enabled false root@openclaw:/# openclaw config set gateway.logLevel warn
OpenClaw writes a openclaw.json.bak before every change. If you break something, your previous config is always one file away.
OpenClaw's state directory lands on the SD card by default. 24/7 write churn will wear it out faster than normal use. Recommendation: attach a USB SSD (~$20) within the first month of always-on operation and set OPENCLAW_STATE_DIR to point to it.
The file at /config/.openclaw/openclaw.json contains your Telegram bot token and gateway auth token. Never share this file, paste it in forums, or commit it to a public git repo. If exposed: revoke the Telegram token via @BotFather → /mybots → Revoke, and regenerate the gateway token with openclaw config set gateway.auth.token $(openssl rand -hex 24).
Skills & Tips
The openclaw skills command only lists and inspects. The actual installer is npx clawhub — a separate package manager. This trips up almost everyone.
root@openclaw:/# ls /config/clawd/ AGENTS.md BOOTSTRAP.md HEARTBEAT.md IDENTITY.md SOUL.md TOOLS.md USER.md
The workspace is at /config/clawd/ — this is also where the agent's identity files live.
root@openclaw:/# npx clawhub --workdir /config/clawd install memory ⚠️ Warning: flagged as suspicious by VirusTotal Code Insight. ◆ Install anyway? Yes
The memory skill needs filesystem access to read/write memory files — this triggers the scanner. It's a false positive for official skills. The warning means clawhub's security scanning is working correctly.
The exec skill is called safe-exec on the registry — not exec. Always inspect before installing:
root@openclaw:/# npx clawhub inspect safe-exec safe-exec — Safe command execution with danger pattern detection, risk assessment, user approval workflow, and audit logging. root@openclaw:/# npx clawhub --workdir /config/clawd install safe-exec
root@openclaw:/# npx clawhub --workdir /config/clawd list memory 1.0.2 safe-exec 0.3.4
The /config/clawd/ directory contains your agent's brain as plain Markdown. Edit them directly to give Claw a permanent identity that survives reinstalls:
Who you are — name, timezone, preferences. The agent reads this every session.
Who the agent is — name, personality, vibe. Fill before the bootstrap conversation.
Deep values and long-term behavioral principles.
Instructions for how the agent should use its available tools.
root@openclaw:/# cat > /config/clawd/USER.md << 'EOF' # USER.md - **Name:** Your Name - **Timezone:** Your timezone - **Notes:** Pi 5 + Home Assistant OS EOF
| Command | What it does |
|---|---|
openclaw doctor | Full health check — run this first when anything feels wrong |
openclaw skills list | See all skills and their ready/missing status |
openclaw config get channels.telegram | View current Telegram config |
openclaw status | Quick channel health and session overview |
openclaw logs | Tail live gateway logs |
npx clawhub search <query> | Search the skill registry |
npx clawhub inspect <slug> | Preview a skill before installing |
npx clawhub --workdir /config/clawd list | List installed workspace skills |
openclaw update | Update OpenClaw via npm |
Lessons Learned & Gotchas
HAOS & Architecture
HA 2026.2 renamed Add-ons to "Apps". The sidebar item is now "Apps" and the store is "App Store". Every tutorial written before Feb 2026 has wrong navigation paths.
systemctl doesn't work inside the add-on container. openclaw gateway restart fails with a confusing systemd error. Always restart via the HA Apps UI.
/etc/environment changes don't apply until the add-on restarts. openclaw doctor keeps showing the NODE_COMPILE_CACHE warning until after a container restart. This is expected.
Onboarding Wizard
access_mode defaults to "custom" — change it to "lan_https" via YAML view. The visual editor in the Configuration tab does not expose this field. You must switch to YAML view (top-right toggle) and manually set access_mode: lan_https. If your gateway UI is unreachable after setup, this is almost certainly why.
Saying "No" to skills during onboarding leaves the agent read-only. Without memory and safe-exec, the agent can't save anything to disk. The bootstrap conversation you have on first boot will be forgotten on restart.
The agent tells you what it can't do — listen to it. When Claw says "I don't have file-write access", it's telling you exactly which skill to install next. This self-awareness is a feature.
Skills & CLI
openclaw skill install doesn't exist. The correct command is openclaw skills (plural, list only). The actual installer is npx clawhub --workdir /config/clawd install <slug>.
The exec skill is called "safe-exec" on clawhub, not "exec". Always use npx clawhub inspect <slug> before installing any community skill.
The VirusTotal warning on the memory skill is a false positive. File system access triggers the scanner. Expected for any skill that touches the filesystem.
Security
Telegram groupPolicy "allowlist" with empty allowFrom silently drops all messages. There's no error — messages just disappear. Set groupPolicy to "open" unless you specifically need group allowlisting.
openclaw.json stores your bot token in plain text. Never paste it publicly or commit to git. The openclaw config get command safely redacts it, but the raw file does not.
Every openclaw config set auto-backs up first. A openclaw.json.bak is created before every change. If you break something, your previous config is always one file away.
Hardware
The SD card warning is real but not urgent. Plan to move to a USB SSD within the first month of always-on operation. The Pi 5's faster SD interface helps, but 24/7 log churn will eventually wear any SD card.
After completing all steps, openclaw doctor should show:
- Telegram: ok — bot name confirmed and responding
- No channel security warnings detected
- Memory search: explicitly disabled
- Skills eligible: 6 (memory + safe-exec + 4 built-ins)
- Your Telegram session active in session store
- Plugins: 5 loaded, 0 errors
OpenClaw is running 24/7 on your Pi 5, secured, with persistent memory, safe shell execution, and Telegram integration. The skill registry at clawhub.com has 50+ skills to extend it further.
Comments
Post a Comment