docs
This commit is contained in:
techartdev
@@ -0,0 +1,400 @@
|
||||
# OpenClaw Home Assistant Integration — Full Documentation
|
||||
|
||||
This guide is a complete setup and usage manual for OpenClaw in Home Assistant.
|
||||
|
||||
|
||||
## 1) What this integration does
|
||||
|
||||
OpenClaw connects Home Assistant to your OpenClaw Gateway and gives you:
|
||||
- A native **Assist conversation agent** (`openclaw`)
|
||||
- A built-in **chat card** for dashboards
|
||||
- **Voice input modes** (browser voice and Home Assistant STT)
|
||||
- **Automation services and events**
|
||||
- **Status and telemetry sensors**
|
||||
|
||||
---
|
||||
|
||||
## 2) Before you begin
|
||||
|
||||
## Required
|
||||
- Home Assistant Core **2025.1.0+**
|
||||
- OpenClaw Assistant addon installed and running, or standalone OpenClaw instance running and available over network
|
||||
- A valid gateway auth token/password configured in the OpenClaw addon
|
||||
|
||||
## Recommended
|
||||
- HACS installed (for easiest updates)
|
||||
- Modern browser (Chrome/Edge/Firefox/Safari)
|
||||
- Microphone permission allowed in browser for your Home Assistant URL, if you want to use voice features
|
||||
|
||||
## Important gateway setting
|
||||
OpenClaw’s OpenAI-compatible endpoint is required by this integration.
|
||||
In addon settings, confirm chat completions endpoint support is enabled (for your gateway version/settings model).
|
||||
If you run OpenClaw standalone set `gateway.http.endpoints.chatCompletions.enabled` to `true`
|
||||
|
||||
If this endpoint is disabled, chat and connection checks can fail even when the addon is running.
|
||||
|
||||
---
|
||||
|
||||
## 3) Installation
|
||||
|
||||
## Option A — HACS (recommended)
|
||||
1. Open **HACS → Integrations**.
|
||||
2. Use the **⋮ menu** (top-right) → **Custom repositories**.
|
||||
3. Add repository URL: `https://github.com/techartdev/OpenClawHomeAssistantIntegration`
|
||||
4. Category: **Integration**.
|
||||
5. Install **OpenClaw**.
|
||||
6. Restart Home Assistant.
|
||||
7. Go to **Settings → Devices & Services → Add Integration**.
|
||||
8. Add **OpenClaw**.
|
||||
|
||||
## Option B — Manual installation
|
||||
1. Copy `custom_components/openclaw` into your Home Assistant config folder.
|
||||
2. Restart Home Assistant.
|
||||
3. Add integration from **Settings → Devices & Services**.
|
||||
|
||||
---
|
||||
|
||||
## 4) Initial setup flow
|
||||
|
||||
When adding the integration, it attempts:
|
||||
1. **Auto-discovery** (if Supervisor/addon metadata is available)
|
||||
2. **Manual setup** fallback (host/port/token)
|
||||
|
||||
If auto-discovery succeeds:
|
||||
- Confirm discovered host/port
|
||||
- Submit
|
||||
|
||||
If manual setup is needed:
|
||||
- Enter gateway host
|
||||
- Enter gateway port
|
||||
- Enter auth token/password value expected by gateway
|
||||
- Enable SSL only if your gateway endpoint is HTTPS
|
||||
|
||||
After setup, Home Assistant creates OpenClaw entities and services automatically.
|
||||
|
||||
---
|
||||
|
||||
## 5) Dashboard chat card
|
||||
|
||||
The chat card is auto-registered by the integration. You can add it from dashboard card picker.
|
||||
|
||||
### Card behavior
|
||||
- Restores chat history for active session
|
||||
- Shows typing/thinking indicator
|
||||
- Supports text and voice interactions
|
||||
- Shows gateway connection badge in header (`Online`, `Offline`, or `Unknown`)
|
||||
|
||||
### Session behavior in the card
|
||||
- Card uses a session id (default session if not overridden)
|
||||
- Keep the same session id to continue conversations
|
||||
- Different session ids isolate conversations
|
||||
- You can add different chat cards on different dashboards and set different session id, this way you keep them as separate conversations
|
||||
|
||||
---
|
||||
|
||||
## 6) Voice features (important)
|
||||
|
||||
OpenClaw supports two voice input providers:
|
||||
|
||||
## A) Browser voice provider
|
||||
- Uses browser speech recognition APIs, free and doesn't need voice integrations installed in HA
|
||||
- Supports:
|
||||
- Manual mic capture
|
||||
- Continuous voice mode
|
||||
- Optional wake-word gating
|
||||
|
||||
Best for users who want continuous conversational voice mode.
|
||||
|
||||
## B) Home Assistant STT provider (`assist_stt`)
|
||||
- Uses Home Assistant STT pipeline endpoint
|
||||
- Designed for **manual** voice capture (press mic, speak, transcribe)
|
||||
- Requires an STT engine configured in Home Assistant Voice settings
|
||||
|
||||
### Continuous mode + assist_stt
|
||||
If continuous voice mode is enabled while provider is `assist_stt`, the card uses browser speech for continuous listening.
|
||||
This is expected behavior in current architecture. Assist STT does not support continuous audio.
|
||||
|
||||
### Wake word setting
|
||||
- `Wake word enabled` controls whether continuous mode requires wake phrase before sending recognized speech.
|
||||
- If disabled, continuous mode can send finalized recognized phrases directly.
|
||||
- Wake-word logic applies to continuous mode behavior, not manual one-shot mic usage.
|
||||
|
||||
### Browser notes
|
||||
- Brave may produce speech backend errors depending on environment/policies.
|
||||
- Chrome/Edge are often more consistent for browser speech APIs.
|
||||
|
||||
---
|
||||
|
||||
## 7) Integration options (Configure screen)
|
||||
|
||||
Path: **Settings → Devices & Services → OpenClaw → Configure**
|
||||
|
||||
### Context options
|
||||
- **Include exposed entities context**
|
||||
- Adds context from entities exposed to voice assistant.
|
||||
- **Max context characters**
|
||||
- Safety limit for injected context size.
|
||||
- **Context strategy**
|
||||
- `truncate`: keep beginning up to max
|
||||
- `clear`: drop context when too large
|
||||
|
||||
### Tool-call option
|
||||
- **Enable tool calls (execute services)**
|
||||
- Allows supported tool-call responses to execute Home Assistant services.
|
||||
- Keep disabled if you prefer read-only assistant behavior.
|
||||
|
||||
### Voice options
|
||||
- **Wake word enabled**
|
||||
- **Wake word**
|
||||
- **Allow Web Speech in Brave (experimental)** (currently may not work, but voice support in Brave is expected in future)
|
||||
- **Voice input provider** (`browser` or `assist_stt`)
|
||||
|
||||
Note: Legacy always-on voice option is removed.
|
||||
|
||||
---
|
||||
|
||||
## 8) Home Assistant Assist integration
|
||||
|
||||
OpenClaw registers as a native Assist conversation agent. This means that you can select OpenClaw as agent in the HA Assist feature and the Assist dialog.
|
||||
|
||||
To use:
|
||||
1. Open Voice Assistants settings.
|
||||
2. Select OpenClaw as the conversation agent where desired.
|
||||
3. Ensure exposed entities and pipeline language settings are configured as expected.
|
||||
|
||||
If responses are unexpected:
|
||||
- Check selected conversation agent
|
||||
- Check exposed entities list
|
||||
- Confirm pipeline STT/TTS language settings
|
||||
|
||||
---
|
||||
|
||||
## 9) Services you can use in automations
|
||||
|
||||
## `openclaw.send_message`
|
||||
Use this to send text to OpenClaw from scripts/automations.
|
||||
|
||||
Use cases:
|
||||
- Trigger assistant checks on schedule
|
||||
- Ask model to summarize state
|
||||
- Start guided routines
|
||||
|
||||
Automation example (scheduled morning summary):
|
||||
|
||||
```yaml
|
||||
alias: OpenClaw Morning Summary
|
||||
trigger:
|
||||
- platform: time
|
||||
at: "08:00:00"
|
||||
action:
|
||||
- service: openclaw.send_message
|
||||
data:
|
||||
message: "Give me a short morning summary for home status and weather."
|
||||
session_id: "daily-briefing"
|
||||
mode: single
|
||||
```
|
||||
|
||||
## `openclaw.clear_history`
|
||||
Clears stored integration-side history for a specific session (or default/all depending call).
|
||||
|
||||
Use cases:
|
||||
- Reset context for new workflow
|
||||
- Recover from stale context
|
||||
|
||||
Automation example (clear context every night):
|
||||
|
||||
```yaml
|
||||
alias: OpenClaw Clear Night Session
|
||||
trigger:
|
||||
- platform: time
|
||||
at: "23:59:00"
|
||||
action:
|
||||
- service: openclaw.clear_history
|
||||
data:
|
||||
session_id: "daily-briefing"
|
||||
mode: single
|
||||
```
|
||||
|
||||
## `openclaw.invoke_tool`
|
||||
Directly invokes one OpenClaw gateway tool through `/tools/invoke`.
|
||||
|
||||
Typical fields in UI:
|
||||
- Tool name
|
||||
- Action
|
||||
- Args object
|
||||
- Session key
|
||||
- Optional channel/account routing hints
|
||||
|
||||
Use cases:
|
||||
- Admin/diagnostic tool calls
|
||||
- Session list retrieval
|
||||
- Controlled operations exposed by gateway policy
|
||||
|
||||
Automation example (diagnostic sessions list on startup):
|
||||
|
||||
```yaml
|
||||
alias: OpenClaw Sessions Diagnostic On Start
|
||||
trigger:
|
||||
- platform: homeassistant
|
||||
event: start
|
||||
action:
|
||||
- service: openclaw.invoke_tool
|
||||
data:
|
||||
tool: sessions_list
|
||||
action: json
|
||||
args: {}
|
||||
session_key: main
|
||||
mode: single
|
||||
```
|
||||
|
||||
Security note:
|
||||
Tool availability is still controlled by gateway policy and deny-lists.
|
||||
|
||||
---
|
||||
|
||||
## 10) Events for automations
|
||||
|
||||
## `openclaw_message_received`
|
||||
Fires when OpenClaw sends a response.
|
||||
|
||||
Useful for:
|
||||
- Notifications
|
||||
- Logging
|
||||
- Chained automations
|
||||
|
||||
Automation example (notify on every assistant reply):
|
||||
|
||||
```yaml
|
||||
alias: OpenClaw Reply Notification
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: openclaw_message_received
|
||||
action:
|
||||
- service: notify.mobile_app_my_phone
|
||||
data:
|
||||
message: "OpenClaw: {{ trigger.event.data.message }}"
|
||||
mode: queued
|
||||
```
|
||||
|
||||
## `openclaw_tool_invoked`
|
||||
Fires after `openclaw.invoke_tool` completes.
|
||||
|
||||
Includes success/failure metadata and timing info, useful for:
|
||||
- Alerting on failed tool runs
|
||||
- Telemetry dashboards
|
||||
- Automation branching based on `ok/error`
|
||||
|
||||
Automation example (alert on tool failure):
|
||||
|
||||
```yaml
|
||||
alias: OpenClaw Tool Failure Alert
|
||||
trigger:
|
||||
- platform: event
|
||||
event_type: openclaw_tool_invoked
|
||||
condition:
|
||||
- condition: template
|
||||
value_template: "{{ trigger.event.data.ok == false }}"
|
||||
action:
|
||||
- service: persistent_notification.create
|
||||
data:
|
||||
title: "OpenClaw Tool Failed"
|
||||
message: >-
|
||||
Tool: {{ trigger.event.data.tool }}
|
||||
Error: {{ trigger.event.data.error }}
|
||||
Duration: {{ trigger.event.data.duration_ms }} ms
|
||||
mode: queued
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11) Entities and sensors
|
||||
|
||||
## Core status entities
|
||||
- **Connected** (binary sensor)
|
||||
- **Status** (`online`/`offline`)
|
||||
- **Last Activity**
|
||||
- **Model**
|
||||
- **Session Count**
|
||||
|
||||
## Tool telemetry sensors
|
||||
- **Last Tool**
|
||||
- **Last Tool Status**
|
||||
- **Last Tool Duration**
|
||||
- **Last Tool Invoked**
|
||||
|
||||
### Why some sensors may show `Unknown`
|
||||
- `Last Tool*` sensors remain `Unknown` until at least one tool invocation completes.
|
||||
- `Session Count` can remain `0` if tool policy blocks `sessions_list` over HTTP invoke endpoint.
|
||||
|
||||
---
|
||||
|
||||
## 12) Troubleshooting
|
||||
|
||||
## Integration cannot connect
|
||||
Check:
|
||||
- Addon is running
|
||||
- Host/port/token are correct
|
||||
- Gateway auth mode matches what you entered
|
||||
- Chat completions endpoint is enabled in gateway settings
|
||||
|
||||
## Chat responses missing on card
|
||||
Check:
|
||||
- Dashboard loaded latest card resource (hard refresh)
|
||||
- `openclaw_message_received` event firing
|
||||
- Session id consistency between message source and card
|
||||
|
||||
## Voice issues
|
||||
Check:
|
||||
- Browser mic permission for Home Assistant URL
|
||||
- Correct provider selected (`browser` vs `assist_stt`)
|
||||
- STT engine configured in HA voice settings (for `assist_stt`)
|
||||
- Browser compatibility (try Chrome/Edge if Brave is unstable)
|
||||
|
||||
## Conversation context seems reset
|
||||
Check:
|
||||
- Same session id is used across turns
|
||||
- Gateway session routing is active
|
||||
- Gateway policy/routing not forcing isolated sessions
|
||||
|
||||
---
|
||||
|
||||
## 13) Best practices
|
||||
|
||||
- Keep one session id per topic/workflow.
|
||||
- Use separate sessions for unrelated automations.
|
||||
- Keep tool calls permissioned and minimal.
|
||||
- Prefer explicit automations for critical actions.
|
||||
- Review logs after upgrades and hard-refresh dashboard resources.
|
||||
|
||||
---
|
||||
|
||||
## 14) Operational checklist (quick)
|
||||
|
||||
After install/update:
|
||||
1. Restart Home Assistant
|
||||
2. Hard refresh dashboard browser tab
|
||||
3. Verify OpenClaw entities are available
|
||||
4. Send one text chat test
|
||||
5. Test voice provider you plan to use
|
||||
6. If using tools, run one `invoke_tool` test and verify telemetry sensors/events
|
||||
|
||||
---
|
||||
|
||||
## 15) Audience-specific quick paths
|
||||
|
||||
## Non-technical path
|
||||
- Install via HACS
|
||||
- Add integration
|
||||
- Add card
|
||||
- Use text first
|
||||
- Enable voice after basic chat works
|
||||
|
||||
## Technical path
|
||||
- Validate gateway endpoint behavior and auth mode
|
||||
- Validate session routing behavior
|
||||
- Build automations with service calls/events
|
||||
- Use telemetry sensors for health and troubleshooting
|
||||
|
||||
---
|
||||
|
||||
If you want this guide split into separate files later (Install, Voice, Automation, Troubleshooting), you can keep this `DOCS.md` as the master index and link each specialized document from it.
|
||||
Reference in New Issue
Block a user