homeai/homeai-voice/TROUBLESHOOTING.md

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