Talk to your OpenClaw AI agent through Home Assistant's voice control and Assist — and let it talk back, unprompted, on your voice satellites.
OpenClaw is an open-source AI agent that runs locally on your machine. It can browse the web, manage email and calendar, access files, run commands, and integrate with 50+ services (Gmail, GitHub, Spotify, Obsidian, …), using Claude, GPT, or local models. This integration exposes your entire agent — its skills, integrations, memory, and context — as a Home Assistant conversation agent. Whatever your OpenClaw does in WhatsApp, Telegram, or Discord, it can now do through your smart-home voice assistant.
- Features
- Entities
- Services
- Requirements
- Installation
- Configuration
- Usage
- Feature guides
- Remote gateway setup
- Troubleshooting
- Limitations
- Security
- Contributing
- Credits & support
Agent
- Full agent access — every skill, integration, memory, and model you've configured in OpenClaw, reachable by voice or text.
- Multi-model — uses whatever model OpenClaw runs (Claude, GPT, local), with optional per-integration model and thinking-mode overrides.
Conversation
- Assist conversation agent — drop-in agent for any Home Assistant voice pipeline or the Assist text box.
- Streaming responses — streams partial output on HA versions that support it, with automatic fallback to buffered responses on older versions.
- Multi-turn voice — when the agent asks a follow-up question, the satellite's mic stays open so you can answer without repeating the wake word. Automatic, no setup. Details ›
- Background work — long-running requests get an "on it" acknowledgment and the result is announced on your satellite when it's ready, instead of a timeout error. On by default. Details ›
- Proactive voice (opt-in) — let the agent speak first on a satellite
(reminders, "task done", follow-ups) via
assist_satellite.announce/start_conversation. Details › - TTS hygiene — optional emoji stripping and length trimming for clean speech.
Connection & auth
- Direct WebSocket — real-time, persistent connection to the OpenClaw Gateway.
- Token + device identity — Gateway token plus an Ed25519 device keypair; remote devices approve once, local connections auto-approve.
- Resilient — keepalive pings, automatic reconnect, reauth flow, and HA repair issues when a token/pairing needs attention.
- Sessions & agent routing — route HA conversations to a specific OpenClaw session and/or agent; switch sessions on the fly. Details ›
Operations
- Diagnostic entities — gateway uptime, connected clients, health, and a connectivity binary sensor. See entities ›
- Diagnostics download + UI-based configuration, multiple gateways, and a
reconnectservice.
Each gateway you add creates one device, OpenClaw Gateway, with:
| Entity | Type | Category | Reports |
|---|---|---|---|
conversation.openclaw |
Conversation | — | Your OpenClaw agent — select it as a conversation agent in Assist |
| OpenClaw Gateway Uptime | Sensor | Diagnostic | Gateway uptime, in seconds |
| OpenClaw Connected Clients | Sensor | Diagnostic | Number of clients connected to the gateway |
| OpenClaw Gateway Health | Sensor | Diagnostic | Health status (e.g. ok) with version/uptime attributes |
| Gateway Connectivity | Binary sensor | Diagnostic | connected / disconnected |
The conversation entity also exposes the active host, port, session, agent, model, thinking mode, and TTS/proactive settings as state attributes.
Exact entity IDs are generated by Home Assistant and may differ from the examples here — check Developer Tools → States for the ones in your install.
| Service | Fields | Description |
|---|---|---|
openclaw.reconnect |
entry_id (optional) |
Force a reconnect for one entry, or all entries if omitted. |
openclaw.set_session |
session_key (required), entry_id (optional) |
Switch the active OpenClaw session for new requests. |
# Example: switch the active session
action: openclaw.set_session
data:
session_key: "voice-assistant"- Home Assistant 2024.1.0 or later. Streaming and multi-turn voice use newer
Assist APIs and degrade gracefully on older versions; proactive voice needs
an
assist_satelliteentity (e.g. Home Assistant Voice PE) on a recent HA. - A configured OpenClaw install with the Gateway running (local or remote).
- A Gateway token (required since OpenClaw 2026.2.13+).
OpenClaw runs on macOS, Windows, and Linux. Install and configure it — with your chosen model and any service integrations — before connecting Home Assistant.
- Open HACS → Integrations → ⋮ → Custom repositories.
- Add this repository URL with category Integration, then Add.
- Search for OpenClaw Voice Assistant and Download.
- Restart Home Assistant.
Pre-release builds: enable Show beta versions in the integration's HACS page to install beta tags (e.g.
1.7.0-beta.1).
- Copy
custom_components/openclawinto your Home Assistantcustom_componentsdirectory. - Restart Home Assistant.
See MIGRATION.md for the step-by-step rename/upgrade guide.
Authentication is mandatory for all connections (including localhost) since OpenClaw 2026.2.13+.
# Generate a new token
openclaw doctor --generate-gateway-token
# → prints e.g. 666c291bc8427a2dfb9e16e8871f2eec59f3e2ffee202a5f
# Or read an existing one from the environment
echo $OPENCLAW_GATEWAY_TOKENTo allow connections from a Home Assistant instance on another machine, bind the gateway to your LAN (and prefer SSL/TLS or an SSH tunnel for anything off-box):
openclaw gateway --bind lan- Settings → Devices & Services → Add Integration → "OpenClaw Voice Assistant".
- Connection — enter:
- Host — gateway hostname/IP (e.g.
192.168.1.100; default127.0.0.1) - Port — gateway port (default
18789) - Gateway Token — your token (required)
- Use SSL — enable for
wss://(recommended for remote) - Agent Timeout — max seconds to wait for an inline reply (default 300, range 5–600); requests deferred to background work get their own 1-hour budget
- Host — gateway hostname/IP (e.g.
- Device approval (first connect only):
- Local / localhost → auto-approved, setup continues immediately.
- Remote → a Device Approval Required step appears. Approve it, then
Submit:
This is a one-time step — the device key is persisted and reused on every future connection and restart.
openclaw devices list openclaw devices approve <device-id> # or use the OpenClaw Control UI
- Session & speech options — every field here is optional and can be changed later via Configure. See the options reference for the full list (session, agent, model, thinking, emoji/TTS, and proactive voice).
All of these are editable any time via Settings → Devices & Services → OpenClaw → Configure.
| Option | Default | Description |
|---|---|---|
| Host | 127.0.0.1 |
Gateway hostname or IP |
| Port | 18789 |
Gateway port |
| Gateway Token | — | Authentication token (required) |
| Use SSL | Off | Use wss:// (recommended for remote) |
| Agent Timeout | 300 s |
Max wait for an inline reply (5–600); deferred runs get a 1-hour budget instead |
| Session Key | main |
OpenClaw session to route HA conversations to |
| Agent | gateway default | Route to a specific gateway agent (keys the session as agent:<id>:<session>) |
| Model override | gateway default | Per-integration model (e.g. anthropic/claude-...) |
| Thinking mode | gateway default | off / low / medium / high |
| Strip emojis from TTS | On | Remove emojis from spoken output |
| TTS max characters | 0 (no limit) |
Trim long spoken replies (0–2000) |
| Background work | On | Slow requests answer later via announce instead of timing out |
| Grace period | 10 s |
Silence before a request is deferred to background (3–60) |
| Holding phrase | “On it — I’ll let you know when it’s done.” | Spoken when a request is deferred |
| Proactive voice | Off | Let the agent speak first on a satellite |
| Satellite to speak on | — | assist_satellite entity used for proactive announcements |
| Proactive mode | announce |
announce (speak) or start_conversation (speak + reopen mic) |
- Settings → Voice Assistants → Assist (or your pipeline of choice).
- Under Conversation agent, select OpenClaw.
- Save.
- Voice — any HA voice interface (mobile app, Voice PE /
assist_satellite, etc.). - Text — the Assist box in the HA UI.
- Automations — call the agent programmatically (see below).
Email & communication
- "Do I have any important emails from [person]?"
- "Send an email to [person] about tomorrow's meeting"
- "Who sent me a Telegram message?"
Calendar & scheduling
- "What's on my calendar today?"
- "Add a dentist appointment next Tuesday at 2pm"
Information & web
- "Search for restaurants near me"
- "Browse to [website] and summarize the main article"
Files & notes
- "Find my notes about [topic]"
- "Save this to my notes: [content]"
Conversational
- "Who are you?", "Explain how photosynthesis works", "Tell me a joke"
Exact capabilities depend on your OpenClaw configuration, skills, and service integrations. For simple device control ("turn on the lights"), prefer Home Assistant's built-in intents — see Limitations.
The conversation entity is callable from any script or automation via
conversation.process — ask the agent something on a schedule and act on the
reply (e.g. a spoken morning briefing):
action: conversation.process
data:
# Your OpenClaw conversation entity id — find it in Developer Tools → States.
agent_id: conversation.openclaw
text: "Give me a one-sentence summary of today's calendar."
response_variable: result
# …then, for example, speak it:
action: assist_satellite.announce
target:
entity_id: assist_satellite.kitchen
data:
message: "{{ result.response.speech.plain.speech }}"When the agent's reply asks a follow-up question, the integration sets
continue_conversation so the satellite keeps its mic open — you can answer
without saying the wake word again. It works automatically, requires no
configuration, and falls back cleanly on HA versions that don't support the flag.
A voice turn is synchronous — the satellite expects speech back within seconds. But agent work like browsing the web or triaging email can stay silent for minutes. Instead of ending in “the response took too long”, the integration races every request against a short grace period (default 10s):
- Agent starts talking in time → the answer streams inline, exactly as normal.
- Still silent when the grace period ends → the assistant speaks the holding phrase (“On it — I’ll let you know when it’s done.”), the run continues in the background, and the result is announced when it finishes — on the satellite you spoke to, falling back to the configured proactive satellite. Failures are announced too, so a deferred request never goes silent.
On by default; tune or disable it under Configure (Background work, Grace period, Holding phrase). It works even with proactive voice off — the report-back speaks directly on the originating satellite.
The race measures your agent’s time-to-first-content, not question difficulty. A heavyweight agent (big model, thinking enabled) can take longer than the grace period to say anything — then even “what time is it?” defers and gets announced a moment later. If that happens, make the voice agent fast rather than the grace long: set Thinking mode to
offand/or a fast Model override in this integration’s options, or route to a voice-optimized session. Raising Grace period works too, at the cost of slower deferral for genuinely long work.
By default the assistant only speaks when spoken to. Proactive voice (opt-in) lets the agent speak first on a satellite — announcing a reminder, telling you a background task finished, or asking a follow-up.
Enable it under Configure:
- Proactive voice — turn it on (off by default).
- Satellite to speak on — the
assist_satelliteentity (e.g. Voice PE). - Proactive mode:
announce— speak the message.start_conversation— speak it and reopen the mic for your reply.
Replies you trigger yourself are never re-announced — only agent-initiated turns are.
It needs a trigger. Proactive voice is a delivery mechanism: it speaks when the gateway produces a proactive turn — an agent cron job, a background task, or the agent choosing to message you. With none of those configured on the OpenClaw side, you won't hear anything. Set up agent reminders/cron in OpenClaw to give it something to say.
The Session Key routes HA conversations to a specific OpenClaw session:
main(default) — the standard direct-chat session.- Custom — isolate or organize HA conversations (e.g.
voice-assistant,automation).
Switch sessions dynamically without reconfiguring via openclaw.set_session (see
Services). If you run multiple agents, set the Agent option to
route to one; the session is then keyed as agent:<id>:<session>.
Set Model override and Thinking mode under Configure to use a specific model or reasoning depth for requests from this integration, independent of your other OpenClaw channels.
Strip emojis from TTS speech (default on) removes emojis from spoken output for cleaner TTS:
- "I'm Claude 🦞" → speaks "I'm Claude" (emoji still visible in chat history).
- Disable it if your TTS engine handles emojis well, or if you mostly use the text Assist box.
TTS max characters caps spoken replies:
0(default) — no limit.> 0— trim to that many characters (an ellipsis is added when trimmed).
For the most natural voice experience, point the integration at a dedicated OpenClaw session whose system prompt is tuned for speech:
You are a voice assistant for a smart home. Keep responses:
- Brief and conversational (1–3 sentences when possible)
- Natural for text-to-speech (no bullet points, formatting, or code blocks)
- Free of emojis and special characters
- Direct and to the point
When performing tasks (email, calendar, …), confirm the action briefly.
Then set Session Key to that session under Configure. Your other OpenClaw channels (Telegram, Discord, …) keep their own settings. See the OpenClaw docs for configuring sessions and prompts.
Add more than one gateway — each needs a unique host:port. You get a separate
conversation entity and device per gateway, and can assign different agents to
different voice pipelines.
- Host:
gateway.example.comor IP · Port:18789· Use SSL: ✓ · Token: required - Approve the device once in OpenClaw on first connect (see Setup walkthrough).
# Run on the Home Assistant machine
ssh -N -L 18789:localhost:18789 user@gateway-hostThen configure Host 127.0.0.1, Port 18789, token required. Over the tunnel the
connection looks local to OpenClaw, so device pairing is typically auto-approved.
Cannot reach the gateway
- Confirm it's running:
openclaw status. Verify host/port and firewall. Enable SSL if the remote requires it.
Authentication failed / invalid token
- Re-check the token (
echo $OPENCLAW_GATEWAY_TOKEN) or generate a new one (openclaw doctor --generate-gateway-token) and update it under Configure.
Device approval required
- Appears on first connect from a remote machine. Approve with
openclaw devices approve <device-id>(or the Control UI), then Submit. One-time only.
Device pairing required (repair issue)
- If a previously approved device loses pairing (e.g. an OpenClaw data reset), a repair issue appears. Re-approve in OpenClaw, then reload the integration.
Response timeout
- With Background work on (the default), slow requests defer to a background announce instead of timing out, so “the response took too long” should be rare — it means Background work is off. A deferred run gets its own budget (1 hour, independent of Agent Timeout); if it still hasn’t finished by then, that is announced too. The Agent Timeout only governs inline (non-deferred) replies, so it’s safe to keep it short for snappy voice failures.
Protocol mismatch
- Means the integration and gateway speak different protocol versions. Update both the integration (HACS) and OpenClaw to current releases.
Diagnostics & logs
- Download diagnostics: Settings → Devices & Services → OpenClaw → ⋮ → Download diagnostics.
- Enable debug logging:
(The logger name is
logger: logs: custom_components.openclaw: debug
custom_components.openclaw.)
- Response time — typical queries take 5–10s; agent tasks (email, web, files) can take 15–30s+. That's slower than rule-based assistants (1–2s) but far more capable.
- Device control — the agent excels at information, tasks, and agentic workflows. For simple control ("turn on the lights"), Home Assistant's native intents are faster and more reliable; run them alongside OpenClaw.
- Context — in-HA conversation history is managed by HA's ChatLog; OpenClaw's own cross-platform memory is unaffected.
- Proactive voice — only speaks when the gateway produces a proactive turn (see
Proactive voice), and requires an
assist_satelliteentity. - Background work across restarts — a request deferred to background is dropped if Home Assistant restarts before it finishes (the gateway run continues; with proactive voice enabled its answer can still arrive). While a deferred run is in flight, proactive announcements are held back to avoid double-speaking its result.
- Two-factor — every connection uses both a Gateway token and a unique Ed25519 device keypair.
- Encrypted at rest — tokens and device keys are stored encrypted by Home Assistant.
- Pairing approval — remote devices require one-time approval; local connections auto-approve.
- Transport — use SSL/TLS (or an SSH tunnel) for anything off-box; the integration warns when connecting to a non-localhost host without SSL.
- The token grants full access to your agent — keep it secret.
Issues and PRs welcome. See ROADMAP.md for what's shipped and what's being considered, GATEWAY_API.md for the Gateway API reference, and AGENTS.md for tuning agents for voice. Keep behavior changes opt-in or clearly called out — don't change defaults for existing users without a note.
- OpenClaw — open-source local AI agent system · openclaw.ai · docs
- This integration — community Home Assistant integration for the OpenClaw Gateway, maintained by @ddrayne. Thanks to contributors @IsakCode222 (multi-turn voice) and @thezapalsky (action-run responses).
- Support — GitHub Issues · Home Assistant Community
Apache License 2.0 — see LICENSE.