techartdev
242 lines
5.2 KiB
Markdown
242 lines
5.2 KiB
Markdown
# OpenClaw Integration for Home Assistant
|
|
|
|
|
|
|
|
OpenClaw is a Home Assistant custom integration that connects your HA instance to the OpenClaw assistant backend and provides:
|
|
|
|
- A native conversation agent for Assist
|
|
- A Lovelace chat card with session history
|
|
- Service and event APIs for automations
|
|
- Optional voice mode in the card
|
|
|
|
---
|
|
|
|
## What it includes
|
|
|
|
- **Conversation agent** (`openclaw`) in Assist / Voice Assistants
|
|
- **Lovelace chat card** (`custom:openclaw-chat-card`) with:
|
|
- message history restore,
|
|
- typing indicator,
|
|
- optional voice input,
|
|
- wake-word handling for continuous mode
|
|
- **Services**
|
|
- `openclaw.send_message`
|
|
- `openclaw.clear_history`
|
|
- **Event**
|
|
- `openclaw_message_received`
|
|
- **Sensors / status entities** for model and connection state
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Home Assistant with Supervisor support for addon discovery
|
|
- OpenClaw Assistant addon installed and running
|
|
|
|
The integration auto-detects the addon. You do not need to manually set an API base URL.
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Option A: HACS (recommended)
|
|
|
|
1. Open **HACS → Integrations**
|
|
2. Click the **3 dots (⋮)** menu in the top-right
|
|
3. Select **Custom repositories**
|
|
4. Add repository URL: `https://github.com/techartdev/OpenClawHomeAssistantIntegration`
|
|
5. Category: **Integration**
|
|
6. Click **Add**
|
|
7. Go back to **Explore & Download Repositories**
|
|
8. Search for **OpenClaw** and install
|
|
9. Restart Home Assistant
|
|
10. Open **Settings → Devices & Services → Add Integration**
|
|
11. Add **OpenClaw**
|
|
|
|
### Option B: Manual
|
|
|
|
1. Copy `custom_components/openclaw` into your HA config directory:
|
|
|
|
```
|
|
config/custom_components/openclaw
|
|
```
|
|
|
|
2. Restart Home Assistant
|
|
3. Add **OpenClaw** from **Settings → Devices & Services**
|
|
|
|
---
|
|
|
|
## Dashboard card
|
|
|
|
The card is registered automatically by the integration.
|
|
|
|
```yaml
|
|
type: custom:openclaw-chat-card
|
|
title: OpenClaw Chat
|
|
height: 500px
|
|
show_timestamps: true
|
|
show_voice_button: true
|
|
show_clear_button: true
|
|
session_id: default
|
|
```
|
|
|
|
Minimal config:
|
|
|
|
```yaml
|
|
type: custom:openclaw-chat-card
|
|
```
|
|
|
|
---
|
|
|
|
## Assist entity exposure context
|
|
|
|
OpenClaw can include Home Assistant entity context based on Assist exposure.
|
|
|
|
Configure exposure in:
|
|
|
|
**Settings → Voice assistants → Expose**
|
|
|
|
Only entities exposed there are included when this feature is enabled.
|
|
|
|
---
|
|
|
|
## Integration options
|
|
|
|
Open **Settings → Devices & Services → OpenClaw → Configure**.
|
|
|
|
### Context options
|
|
|
|
- **Include exposed entities context**
|
|
- **Max context characters**
|
|
- **Context strategy**
|
|
- `truncate`: keep the first part up to max length
|
|
- `clear`: remove context when it exceeds max length
|
|
|
|
### Tool call option
|
|
|
|
- **Enable tool calls**
|
|
|
|
When enabled, OpenClaw tool-call responses can execute Home Assistant services.
|
|
|
|
### Voice options
|
|
|
|
- **Wake word enabled**
|
|
- **Wake word** (default: `hey openclaw`)
|
|
- **Always voice mode** (continuous listening while card is open)
|
|
|
|
---
|
|
|
|
## Browser voice note (important)
|
|
|
|
Card voice input uses browser speech recognition APIs (`SpeechRecognition` / `webkitSpeechRecognition`).
|
|
|
|
- Behavior depends on browser support and provider availability
|
|
- In Brave, repeated `network` errors can occur even with mic permission
|
|
- The card now detects repeated backend failures and stops endless retries with a clear status message
|
|
|
|
If voice is unreliable in Brave, use Chrome/Edge for card voice input or continue with typed chat.
|
|
|
|
---
|
|
|
|
## Services
|
|
|
|
### `openclaw.send_message`
|
|
|
|
Send a message to OpenClaw.
|
|
|
|
Fields:
|
|
|
|
- `message` (required)
|
|
- `session_id` (optional)
|
|
- `attachments` (optional)
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
service: openclaw.send_message
|
|
data:
|
|
message: "Turn on the living room lights"
|
|
session_id: "living-room-session"
|
|
```
|
|
|
|
### `openclaw.clear_history`
|
|
|
|
Clear stored conversation history for a session.
|
|
|
|
Fields:
|
|
|
|
- `session_id` (optional; defaults to `default` session)
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
service: openclaw.clear_history
|
|
data:
|
|
session_id: "living-room-session"
|
|
```
|
|
|
|
---
|
|
|
|
## Event
|
|
|
|
### `openclaw_message_received`
|
|
|
|
Fired when OpenClaw returns a response.
|
|
|
|
Event data includes:
|
|
|
|
- `message`
|
|
- `session_id`
|
|
- `timestamp`
|
|
|
|
Automation example:
|
|
|
|
```yaml
|
|
trigger:
|
|
- platform: event
|
|
event_type: openclaw_message_received
|
|
action:
|
|
- service: notify.mobile_app_phone
|
|
data:
|
|
message: "{{ trigger.event.data.message }}"
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Card does not appear
|
|
|
|
- Restart Home Assistant after updating
|
|
- Hard refresh browser cache
|
|
- Confirm Integration is loaded in **Settings → Devices & Services**
|
|
|
|
### Voice button is active but no transcript is sent
|
|
|
|
- Check browser mic permission for your HA URL
|
|
- Open browser console for `OpenClaw: Speech recognition error`
|
|
- If you see repeated `network`, this is usually browser speech backend failure
|
|
|
|
### Responses do not appear after sending
|
|
|
|
- Verify `openclaw_message_received` is being fired in Developer Tools → Events
|
|
- Confirm session IDs match between card and service calls
|
|
|
|
---
|
|
|
|
## Development notes
|
|
|
|
- Main card source is:
|
|
|
|
```
|
|
custom_components/openclaw/www/openclaw-chat-card.js
|
|
```
|
|
|
|
- Root `www/openclaw-chat-card.js` is a loader shim that imports the packaged card script.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT. See [LICENSE](LICENSE).
|