aodhan/homeai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6a0bae2a0be025c484ad60395c8994e3dad2c873
homeai/homeai-agent/custom_components/openclaw_conversation/README.md
Aodhan Collins 6a0bae2a0b feat(phase-04): Wyoming Satellite integration + OpenClaw HA components 
## Voice Pipeline (P3)
- Replace openWakeWord daemon with Wyoming Satellite approach
- Add Wyoming Satellite service on port 10700 for HA voice pipeline
- Update setup.sh with cross-platform sed compatibility (macOS/Linux)
- Add version field to Kokoro TTS voice info
- Update launchd service loader to use Wyoming Satellite

## Home Assistant Integration (P4)
- Add custom conversation agent component (openclaw_conversation)
  - Fix: Use IntentResponse instead of plain strings (HA API requirement)
  - Support both HTTP API and CLI fallback modes
  - Config flow for easy HA UI setup
- Add OpenClaw bridge scripts (Python + Bash)
- Add ha-ctl utility for HA entity control
  - Fix: Use context manager for token file reading
- Add HA configuration examples and documentation

## Infrastructure
- Add mem0 backup automation (launchd + script)
- Add n8n workflow templates (morning briefing, notification router)
- Add VS Code workspace configuration
- Reorganize model files into categorized folders:
  - lmstudio-community/
  - mlx-community/
  - bartowski/
  - mradermacher/

## Documentation
- Update PROJECT_PLAN.md with Wyoming Satellite architecture
- Update TODO.md with completed Wyoming integration tasks
- Add OPENCLAW_INTEGRATION.md for HA setup guide

## Testing
- Verified Wyoming services running (STT:10300, TTS:10301, Satellite:10700)
- Verified OpenClaw CLI accessibility
- Confirmed cross-platform compatibility fixes
2026-03-08 02:06:37 +00:00

3.4 KiB
Raw Blame History

OpenClaw Conversation - Home Assistant Custom Component

A custom conversation agent for Home Assistant that routes all voice/text queries to OpenClaw for processing.

Features

  • Direct OpenClaw Integration: Routes all conversation requests to OpenClaw
  • CLI-based Communication: Uses the openclaw CLI command (fallback if HTTP API unavailable)
  • Configurable: Set host, port, agent name, and timeout via UI
  • Voice Pipeline Compatible: Works with Home Assistant's voice assistant pipeline

Installation

Method 1: Manual Copy

  1. Copy the entire openclaw_conversation folder to your Home Assistant custom_components directory:

    # On the HA host (if using HA OS or Container, use the File Editor add-on)
cp -r homeai-agent/custom_components/openclaw_conversation \
  /config/custom_components/

  2. Restart Home Assistant

  3. Go to Settings → Devices & Services → Add Integration

  4. Search for "OpenClaw Conversation"

  5. Configure the settings:

    • OpenClaw Host: localhost (or IP of Mac Mini)
    • OpenClaw Port: 8080
    • Agent Name: main (or your configured agent)
    • Timeout: 30 seconds

Method 2: Using HACS (if available)

  1. Add this repository to HACS as a custom repository
  2. Install "OpenClaw Conversation"
  3. Restart Home Assistant

Configuration

Via UI (Recommended)

After installation, configure via Settings → Devices & Services → OpenClaw Conversation → Configure.

Via YAML (Alternative)

Add to your configuration.yaml:

openclaw_conversation:
  openclaw_host: localhost
  openclaw_port: 8080
  agent_name: main
  timeout: 30

Usage

Once configured, the OpenClaw agent will be available as a conversation agent in Home Assistant.

Setting as Default Agent

  1. Go to Settings → Voice Assistants
  2. Edit your voice assistant pipeline
  3. Set Conversation Agent to "OpenClaw Conversation"
  4. Save

Testing

  1. Open the Assist panel in Home Assistant
  2. Type a query like: "Turn on the reading lamp"
  3. OpenClaw will process the request and return a response

Architecture

[Voice Input] → [HA Voice Pipeline] → [OpenClaw Conversation Agent]
                                              ↓
                                    [OpenClaw CLI/API]
                                              ↓
                                    [Ollama LLM + Skills]
                                              ↓
                                    [HA Actions + TTS Response]

Troubleshooting

Agent Not Responding

  1. Check OpenClaw is running: pgrep -f openclaw
  2. Test CLI directly: openclaw agent --message "Hello" --agent main
  3. Check HA logs: Settings → System → Logs

Connection Errors

  1. Verify OpenClaw host/port settings
  2. Ensure OpenClaw is accessible from HA container/host
  3. Check network connectivity: curl http://localhost:8080/status

Files

File Purpose
manifest.json Component metadata
__init__.py Component setup and registration
config_flow.py Configuration UI flow
const.py Constants and defaults
conversation.py Conversation agent implementation
strings.json UI translations

See Also