feat: OpenClaw HTTP bridge, HA conversation agent fixes, voice pipeline tooling
- Add openclaw-http-bridge.py: HTTP server translating POST requests to OpenClaw CLI calls - Add launchd plist for HTTP bridge (port 8081, auto-start) - Add install-to-docker-ha.sh: deploy custom component to Docker HA via SSH - Add package-for-ha.sh: create distributable tarball of custom component - Add test-services.sh: comprehensive voice pipeline service checker Fixes from code review: - Use OpenClawAgent (HTTP) in async_setup_entry instead of OpenClawCLIAgent (CLI agent fails inside Docker HA where openclaw binary doesn't exist) - Update all port references from 8080 to 8081 (HTTP bridge port) - Remove overly permissive CORS headers from HTTP bridge - Fix zombie process leak: kill child process on CLI timeout - Remove unused subprocess import in conversation.py - Add version field to Kokoro TTS Wyoming info - Update TODO.md with voice pipeline progress
This commit is contained in:
Aodhan Collins
420
homeai-voice/TROUBLESHOOTING.md
Normal file
420
homeai-voice/TROUBLESHOOTING.md
Normal file
@@ -0,0 +1,420 @@
|
||||
# Voice Pipeline Troubleshooting Guide
|
||||
|
||||
> Common issues and solutions for the voice pipeline setup
|
||||
|
||||
---
|
||||
|
||||
## Network Configuration
|
||||
|
||||
**Important**: The services are split across two machines:
|
||||
|
||||
| Service | Machine | IP Address |
|
||||
|---------|---------|------------|
|
||||
| OpenClaw Gateway | Mac Mini | 10.0.0.101 |
|
||||
| Wyoming STT | Mac Mini | 10.0.0.101 |
|
||||
| Wyoming TTS | Mac Mini | 10.0.0.101 |
|
||||
| Wyoming Satellite | Mac Mini | 10.0.0.101 |
|
||||
| Ollama | Mac Mini | 10.0.0.101 |
|
||||
| Home Assistant | Server (Docker) | 10.0.0.199 |
|
||||
|
||||
---
|
||||
|
||||
## Issue: OpenClaw Conversation Cannot Connect
|
||||
|
||||
### Symptoms
|
||||
- Integration installed but shows connection error
|
||||
- HA logs show timeout or connection refused
|
||||
- Error: "Cannot connect to OpenClaw service"
|
||||
|
||||
### Root Cause
|
||||
The OpenClaw Conversation integration is configured with the wrong host IP. It needs to point to the Mac Mini (10.0.0.101), not the HA server (10.0.0.199).
|
||||
|
||||
### Solution
|
||||
|
||||
1. **Open Home Assistant UI** at http://10.0.0.199:8123
|
||||
|
||||
2. **Go to Settings → Devices & Services**
|
||||
|
||||
3. **Find "OpenClaw Conversation"** integration
|
||||
|
||||
4. **Click "Configure"** (or delete and re-add)
|
||||
|
||||
5. **Set the correct configuration:**
|
||||
- **OpenClaw Host**: `10.0.0.101` (Mac Mini IP, NOT 10.0.0.199)
|
||||
- **OpenClaw Port**: `8080`
|
||||
- **Agent Name**: `main`
|
||||
- **Timeout**: `30`
|
||||
|
||||
6. **Save** and verify connection
|
||||
|
||||
### Verify Network Connectivity
|
||||
|
||||
From the HA server, test if it can reach OpenClaw:
|
||||
|
||||
```bash
|
||||
# SSH to HA server
|
||||
ssh 10.0.0.199
|
||||
|
||||
# Test OpenClaw connectivity
|
||||
curl http://10.0.0.101:8080/status
|
||||
|
||||
# Or use nc
|
||||
nc -z 10.0.0.101 8080 && echo "OpenClaw reachable" || echo "Cannot reach OpenClaw"
|
||||
```
|
||||
|
||||
From the Mac Mini, verify OpenClaw is listening:
|
||||
|
||||
```bash
|
||||
# Check OpenClaw is running
|
||||
launchctl list | grep openclaw
|
||||
|
||||
# Check it's listening on all interfaces
|
||||
lsof -i :8080
|
||||
|
||||
# Test locally
|
||||
curl http://localhost:8080/status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Wyoming Services Cannot Connect
|
||||
|
||||
### Symptoms
|
||||
- Wyoming integrations show as unavailable
|
||||
- HA cannot reach STT/TTS services
|
||||
- Timeout errors in HA logs
|
||||
|
||||
### Solution
|
||||
|
||||
Wyoming services are also on the Mac Mini (10.0.0.101):
|
||||
|
||||
1. **Go to Settings → Devices & Services**
|
||||
|
||||
2. **For each Wyoming integration**, verify the host is set to **10.0.0.101**:
|
||||
- Wyoming STT: `10.0.0.101:10300`
|
||||
- Wyoming TTS: `10.0.0.101:10301`
|
||||
- Wyoming Satellite: `10.0.0.101:10700`
|
||||
|
||||
3. **Test connectivity from HA server:**
|
||||
|
||||
```bash
|
||||
ssh 10.0.0.199
|
||||
nc -z 10.0.0.101 10300 # STT
|
||||
nc -z 10.0.0.101 10301 # TTS
|
||||
nc -z 10.0.0.101 10700 # Satellite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Firewall Blocking Connections
|
||||
|
||||
### Symptoms
|
||||
- Services work locally on Mac Mini
|
||||
- Cannot connect from HA server
|
||||
- Connection timeout errors
|
||||
|
||||
### Solution
|
||||
|
||||
Check Mac Mini firewall settings:
|
||||
|
||||
```bash
|
||||
# Check firewall status
|
||||
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
|
||||
|
||||
# If enabled, add exceptions for the services
|
||||
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /opt/homebrew/bin/ollama
|
||||
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/local/bin/openclaw
|
||||
|
||||
# Or temporarily disable for testing (not recommended for production)
|
||||
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: OpenClaw CLI Not Found in HA Container
|
||||
|
||||
### Symptoms
|
||||
- Integration uses CLI fallback
|
||||
- Error: "OpenClaw CLI not found"
|
||||
- Component works but responses fail
|
||||
|
||||
### Root Cause
|
||||
The `openclaw` command is not available inside the HA Docker container. The integration should use the HTTP API, not CLI.
|
||||
|
||||
### Solution
|
||||
|
||||
The OpenClawCLIAgent is a fallback. Ensure the integration is using the HTTP API:
|
||||
|
||||
1. Check the integration configuration uses the correct host/port
|
||||
2. Verify OpenClaw Gateway is accessible via HTTP
|
||||
3. The component will automatically use HTTP if available
|
||||
|
||||
---
|
||||
|
||||
## Issue: Voice Pipeline Not Responding
|
||||
|
||||
### Symptoms
|
||||
- Wake word detected but no response
|
||||
- Audio captured but not transcribed
|
||||
- Transcription works but no TTS output
|
||||
|
||||
### Debugging Steps
|
||||
|
||||
1. **Check all services are running:**
|
||||
|
||||
```bash
|
||||
# On Mac Mini
|
||||
./homeai-voice/scripts/test-services.sh
|
||||
```
|
||||
|
||||
2. **Test each component individually:**
|
||||
|
||||
```bash
|
||||
# Test wake word detection
|
||||
# Say "Hey Jarvis" and check satellite logs
|
||||
tail -f /tmp/homeai-wyoming-satellite.log
|
||||
|
||||
# Test STT
|
||||
# Check if audio is being transcribed
|
||||
tail -f /tmp/homeai-wyoming-stt.log
|
||||
|
||||
# Test OpenClaw
|
||||
openclaw agent --message "Hello" --agent main
|
||||
|
||||
# Test TTS
|
||||
tail -f /tmp/homeai-wyoming-tts.log
|
||||
```
|
||||
|
||||
3. **Check HA Voice Pipeline configuration:**
|
||||
- Settings → Voice Assistants
|
||||
- Verify pipeline uses correct STT, Conversation, and TTS
|
||||
- Ensure OpenClaw Conversation is selected
|
||||
|
||||
4. **Test from HA Assist:**
|
||||
- Type a query in HA Assist panel
|
||||
- Check if you get a response
|
||||
- This bypasses wake word and audio capture
|
||||
|
||||
---
|
||||
|
||||
## Monitoring Wake Word Detection
|
||||
|
||||
To see when the wake word ("Hey Jarvis") is being detected in real-time:
|
||||
|
||||
### Option 1: Watch Satellite Logs (Recommended)
|
||||
|
||||
The Wyoming Satellite handles wake word detection and audio streaming:
|
||||
|
||||
```bash
|
||||
# Terminal 1: Watch satellite logs
|
||||
tail -f /tmp/homeai-wyoming-satellite.log
|
||||
```
|
||||
|
||||
**What to look for:**
|
||||
- `Wake word detected` - Wake word was heard
|
||||
- `Streaming audio` - Audio being sent to STT
|
||||
- `Connected to server` - Connection status
|
||||
|
||||
### Option 2: Watch Wake Word Service Logs
|
||||
|
||||
```bash
|
||||
# Terminal 1: Watch wake word detection logs
|
||||
tail -f /tmp/homeai-wakeword.log
|
||||
```
|
||||
|
||||
### Option 3: Watch All Voice Pipeline Logs
|
||||
|
||||
```bash
|
||||
# Terminal 1: Watch all voice-related logs
|
||||
tail -f /tmp/homeai-*.log | grep -E "(wake|satellite|stt|tts|openclaw)"
|
||||
```
|
||||
|
||||
### Test Wake Word Detection
|
||||
|
||||
While watching the logs, try this:
|
||||
|
||||
1. **Say clearly**: "Hey Jarvis" (or your configured wake word)
|
||||
2. **Wait** for the acknowledgment beep
|
||||
3. **Speak your command**: "What time is it?"
|
||||
4. **Check logs** for activity
|
||||
|
||||
### Expected Log Output
|
||||
|
||||
When wake word is detected, you should see:
|
||||
|
||||
```
|
||||
[wyoming_satellite] Wake word detected
|
||||
[wyoming_satellite] Streaming audio to stt
|
||||
[wyoming_satellite] Connected to 10.0.0.101:10300
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Audio Playback Not Working
|
||||
|
||||
### Symptoms
|
||||
- Pipeline works but no audio output
|
||||
- TTS generates audio but satellite doesn't play it
|
||||
- Silent responses
|
||||
|
||||
### Solution
|
||||
|
||||
1. **Check audio output device:**
|
||||
|
||||
```bash
|
||||
# On Mac Mini
|
||||
afplay /System/Library/Sounds/Glass.aiff
|
||||
```
|
||||
|
||||
2. **Check satellite configuration:**
|
||||
|
||||
```bash
|
||||
# View satellite config
|
||||
cat ~/Library/LaunchAgents/com.homeai.wyoming-satellite.plist
|
||||
|
||||
# Check logs for audio errors
|
||||
tail -f /tmp/homeai-wyoming-satellite.log
|
||||
```
|
||||
|
||||
3. **Verify SoX is installed:**
|
||||
|
||||
```bash
|
||||
which play
|
||||
brew install sox
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: High Latency (>5 seconds)
|
||||
|
||||
### Symptoms
|
||||
- Long delay between wake word and response
|
||||
- Slow transcription or TTS generation
|
||||
|
||||
### Solutions
|
||||
|
||||
1. **Check network latency:**
|
||||
|
||||
```bash
|
||||
# From HA server to Mac Mini
|
||||
ping 10.0.0.101
|
||||
```
|
||||
|
||||
2. **Check Ollama model size:**
|
||||
|
||||
```bash
|
||||
# Smaller models are faster
|
||||
ollama list
|
||||
|
||||
# Switch to faster model in OpenClaw config
|
||||
# qwen2.5:7b is faster than llama3.3:70b
|
||||
```
|
||||
|
||||
3. **Check system resources:**
|
||||
|
||||
```bash
|
||||
# On Mac Mini
|
||||
top -l 1 | grep -E "CPU|PhysMem"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Correct Configuration Summary
|
||||
|
||||
### OpenClaw Conversation Integration
|
||||
- Host: `10.0.0.101` (Mac Mini)
|
||||
- Port: `8080`
|
||||
- Agent: `main`
|
||||
- Timeout: `30`
|
||||
|
||||
### Wyoming STT Integration
|
||||
- Host: `10.0.0.101` (Mac Mini)
|
||||
- Port: `10300`
|
||||
|
||||
### Wyoming TTS Integration
|
||||
- Host: `10.0.0.101` (Mac Mini)
|
||||
- Port: `10301`
|
||||
|
||||
### Wyoming Satellite Integration
|
||||
- Host: `10.0.0.101` (Mac Mini)
|
||||
- Port: `10700`
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
- [ ] All services running on Mac Mini (10.0.0.101)
|
||||
- [ ] HA can ping Mac Mini: `ping 10.0.0.101`
|
||||
- [ ] HA can reach OpenClaw: `curl http://10.0.0.101:8080/status`
|
||||
- [ ] HA can reach Wyoming STT: `nc -z 10.0.0.101 10300`
|
||||
- [ ] HA can reach Wyoming TTS: `nc -z 10.0.0.101 10301`
|
||||
- [ ] HA can reach Wyoming Satellite: `nc -z 10.0.0.101 10700`
|
||||
- [ ] OpenClaw Conversation integration configured with 10.0.0.101
|
||||
- [ ] Wyoming integrations configured with 10.0.0.101
|
||||
- [ ] Voice pipeline created and set as default
|
||||
- [ ] Test query in HA Assist returns response
|
||||
|
||||
---
|
||||
|
||||
## Bugs Fixed During Setup
|
||||
|
||||
The following bugs were discovered and fixed during initial setup (2026-03-08):
|
||||
|
||||
### 1. OpenClaw Network Binding
|
||||
|
||||
**Problem**: OpenClaw gateway was only listening on localhost (127.0.0.1), not accessible from HA server.
|
||||
|
||||
**Fix**: Added `"bind": "lan"` to `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"gateway": {
|
||||
"port": 8080,
|
||||
"mode": "local",
|
||||
"bind": "lan",
|
||||
"auth": { "token": "..." }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Custom Component API Error
|
||||
|
||||
**Problem**: `async_set_agent()` was being called with `DOMAIN` (string) instead of `entry` (ConfigEntry object).
|
||||
|
||||
**Fix**: Changed parameter in `homeai-agent/custom_components/openclaw_conversation/__init__.py`:
|
||||
|
||||
```python
|
||||
# Line 83
|
||||
conversation.async_set_agent(hass, entry, agent) # Was: DOMAIN
|
||||
|
||||
# Line 94
|
||||
conversation.async_unset_agent(hass, entry) # Was: DOMAIN
|
||||
```
|
||||
|
||||
### 3. TTS Server Missing Version
|
||||
|
||||
**Problem**: `TtsProgram` initialization was missing required `version` parameter.
|
||||
|
||||
**Fix**: Added `version="1.0.0"` in `homeai-voice/tts/wyoming_kokoro_server.py` line 58.
|
||||
|
||||
### 4. Voice Commands Not Working (CLI Not in Docker)
|
||||
|
||||
**Problem**: HA Docker container couldn't access `openclaw` CLI.
|
||||
|
||||
**Fix**: Created OpenClaw HTTP Bridge (`homeai-agent/openclaw-http-bridge.py`) on port 8081 that translates HTTP POST requests to OpenClaw CLI calls. The custom component now uses port 8081 (HTTP bridge) instead of 8080 (gateway).
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If issues persist:
|
||||
|
||||
1. **Check service logs:**
|
||||
- Mac Mini: `/tmp/homeai-*.log`
|
||||
- HA: Settings → System → Logs
|
||||
|
||||
2. **Verify network connectivity** between machines
|
||||
|
||||
3. **Test each component** individually before testing the full pipeline
|
||||
|
||||
4. **Review configuration** in [`VOICE_PIPELINE_SETUP.md`](VOICE_PIPELINE_SETUP.md)
|
||||
Reference in New Issue
Block a user