Tetra-AI-HA-Integration/README.md

OpenClaw Integration for Home Assistant

Join our Discord Server!

If you want to install OpenClaw as Add-On/App directly on your Home Assistant instance take a look here: https://github.com/techartdev/OpenClawHomeAssistant

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
  • openclaw.invoke_tool
• Event
  • openclaw_message_received
  • openclaw_tool_invoked
• Sensors / status entities for model and connection state
  • Includes tool telemetry sensors (Last Tool, Last Tool Status, Last Tool Duration, Last Tool Invoked)

---

Requirements

• Home Assistant Core 2025.1.0+ (declared minimum)
• Supervisor is optional (used for auto-discovery)
• OpenClaw Assistant addon installed and running

The integration can auto-detect the addon when Supervisor is available. You can always configure host/port/token manually.

---

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.

The card header shows live gateway state (Online / Offline) using existing OpenClaw status entities.

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:

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)
• Voice input provider (browser or assist_stt)

Voice provider usage

• browser

  • Uses browser Web Speech recognition.
  • Supports manual mic and continuous voice mode (wake word flow).
  • Best when browser STT is stable in your environment.

• assist_stt

  • Uses Home Assistant STT provider via /api/stt/<provider>.
  • Intended for manual mic input (press mic, speak, auto-stop, transcribe, send).
  • If continuous Voice Mode is enabled while this provider is selected, the card uses browser speech for continuous listening.

For assist_stt, make sure an STT engine is configured in Settings → Voice assistants.

---

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:

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:

service: openclaw.clear_history
data:
  session_id: "living-room-session"

openclaw.invoke_tool

Invoke a single OpenClaw Gateway tool directly.

Fields:

• tool (required)
• action (optional)
• args (optional object)
• session_key (optional)
• dry_run (optional)
• message_channel (optional)
• account_id (optional)

Example:

service: openclaw.invoke_tool
data:
  tool: sessions_list
  action: json
  args: {}
  session_key: main

---

Event

openclaw_message_received

Fired when OpenClaw returns a response.

Event data includes:

• message
• session_id
• timestamp

Automation example:

trigger:
  - platform: event
    event_type: openclaw_message_received
action:
  - service: notify.mobile_app_phone
    data:
      message: "{{ trigger.event.data.message }}"

openclaw_tool_invoked

Fired when openclaw.invoke_tool completes.

Event data includes:

• tool
• ok
• result
• error
• duration_ms
• timestamp

Automation example:

trigger:
  - platform: event
    event_type: openclaw_tool_invoked
condition:
  - condition: template
    value_template: "{{ trigger.event.data.ok == false }}"
action:
  - service: notify.mobile_app_phone
    data:
      message: "Tool {{ trigger.event.data.tool }} failed: {{ trigger.event.data.error }}"

---

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
• Confirm Voice input provider setting in integration options:
  • browser for Web Speech recognition
  • assist_stt for Home Assistant STT transcription
• For browser: open browser console for OpenClaw: Speech recognition error; repeated network usually means browser speech backend failure
• For assist_stt: check network calls to /api/stt/<provider> and verify Home Assistant Voice/STT provider is configured

Tool sensors show Unknown

• Last Tool* sensors stay Unknown until at least one openclaw.invoke_tool service call has executed.
• Session Count remains 0 if gateway policy blocks sessions_list for /tools/invoke.

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.

---

Star History

License

MIT. See LICENSE.

Support / Donations

If you find this useful and you want to bring me a coffee to make more nice stuff, or support the project, use the link below:

• https://revolut.me/vanyo6dhw