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:

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

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

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:

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

# On Mac Mini
./homeai-voice/scripts/test-services.sh

2. Test each component individually:

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

# 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

# Terminal 1: Watch wake word detection logs
tail -f /tmp/homeai-wakeword.log

Option 3: Watch All Voice Pipeline Logs

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

# On Mac Mini
afplay /System/Library/Sounds/Glass.aiff

2. Check satellite configuration:

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

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:

# From HA server to Mac Mini
ping 10.0.0.101

2. Check Ollama model size:

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

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

{
  "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:

# 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