readme update, brave browser workaround for voice
This commit is contained in:
techartdev
@@ -1,106 +1,234 @@
|
||||
# OpenClaw Integration for Home Assistant
|
||||
|
||||
A native Home Assistant integration for communicating with the
|
||||
[OpenClaw Assistant](https://github.com/techartdev/OpenClawHomeAssistant) addon.
|
||||
OpenClaw is a Home Assistant custom integration that connects your HA instance to the OpenClaw assistant backend and provides:
|
||||
|
||||
## Features
|
||||
- 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
|
||||
|
||||
- **Chat card** — Lovelace card with streaming AI responses, file attachments, and voice mode
|
||||
- **Sensors** — `openclaw_status`, `openclaw_model`, `openclaw_session_count`, `openclaw_last_activity`, `openclaw_connected`
|
||||
- **Conversation agent** — appears in Assist & Voice PE as a native agent
|
||||
- **Service calls** — `openclaw.send_message` for automations
|
||||
- **Events** — `openclaw_message_received` for triggering automations from AI responses
|
||||
- **Zero-config** — auto-discovers the addon via Supervisor API, no tokens or URLs to enter
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
### HACS (recommended)
|
||||
### Option A: HACS (recommended)
|
||||
|
||||
1. Open HACS → Integrations → **+ Explore & Download Repositories**
|
||||
2. Search for **OpenClaw** and install
|
||||
3. Restart Home Assistant
|
||||
4. Go to Settings → Devices & Services → **Add Integration → OpenClaw**
|
||||
1. Open **HACS → Integrations**
|
||||
2. Select **Explore & Download Repositories**
|
||||
3. Search for **OpenClaw** and install
|
||||
4. Restart Home Assistant
|
||||
5. Open **Settings → Devices & Services → Add Integration**
|
||||
6. Add **OpenClaw**
|
||||
|
||||
### Manual
|
||||
### Option B: Manual
|
||||
|
||||
1. Copy `custom_components/openclaw` into your HA config directory:
|
||||
|
||||
```
|
||||
config/custom_components/openclaw
|
||||
```
|
||||
|
||||
1. Copy `custom_components/openclaw/` into your HA `config/custom_components/` directory
|
||||
2. Restart Home Assistant
|
||||
3. Add the integration via Settings → Devices & Services
|
||||
3. Add **OpenClaw** from **Settings → Devices & Services**
|
||||
|
||||
## Prerequisites
|
||||
---
|
||||
|
||||
The **OpenClaw Assistant** addon must be installed and running.
|
||||
The integration will auto-detect it — no manual configuration needed.
|
||||
## Dashboard card
|
||||
|
||||
## Exposed entities (important)
|
||||
The card is registered automatically by the integration.
|
||||
|
||||
OpenClaw uses Home Assistant's native **Assist entity exposure** controls.
|
||||
Only entities exposed to Assist are included in the context sent to OpenClaw.
|
||||
```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
|
||||
```
|
||||
|
||||
Configure this in Home Assistant:
|
||||
|
||||
1. Go to **Settings → Voice assistants**
|
||||
2. Open the **Expose** tab
|
||||
3. Select which entities are exposed to **Assist**
|
||||
|
||||
## Advanced options
|
||||
|
||||
Open **Settings → Devices & Services → OpenClaw → Configure** to tune:
|
||||
|
||||
- Include exposed entities context
|
||||
- Max context characters
|
||||
- Context overflow strategy (`truncate` or `clear`)
|
||||
- Enable tool calls (execute HA services from model tool-call responses)
|
||||
- Require wake word
|
||||
- Wake word text (for example: `hey openclaw`)
|
||||
- Always-on voice mode (continuous listening while the card is open)
|
||||
|
||||
## Chat Card
|
||||
|
||||
The chat card is registered automatically when the integration loads — no
|
||||
manual resource configuration needed. Just add it to any dashboard:
|
||||
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 from an automation or script.
|
||||
Send a message to OpenClaw.
|
||||
|
||||
Fields:
|
||||
|
||||
- `message` (required)
|
||||
- `session_id` (optional)
|
||||
- `attachments` (optional)
|
||||
|
||||
Example:
|
||||
|
||||
```yaml
|
||||
service: openclaw.send_message
|
||||
data:
|
||||
message: "What's the weather like today?"
|
||||
session_id: "optional-session-id"
|
||||
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: "optional-session-id"
|
||||
session_id: "living-room-session"
|
||||
```
|
||||
|
||||
## Events
|
||||
---
|
||||
|
||||
## Event
|
||||
|
||||
### `openclaw_message_received`
|
||||
|
||||
Fired whenever OpenClaw sends a response. Use in automations:
|
||||
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
|
||||
- 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
|
||||
|
||||
See [LICENSE](LICENSE).
|
||||
MIT. See [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user