Tetra-AI-HA-Integration/DOCS.md

# 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.