openclaw-voice-assistant/QUICKSTART.md

Quick Start Guide - Bilingual Voice Assistant

AI Now Inc - Del Mar Demo Unit
Laboratory Assistant: Claw 🏭

🚀 Installation (5 minutes)

Step 1: Clone and Install

# Navigate to workspace
cd /home/pi

# Clone or copy the voice-assistant folder
# (If copying from another machine, use scp or git)

# Make install script executable
cd voice-assistant
chmod +x install.sh

# Run installation
sudo ./install.sh

Step 2: Configure

Edit the configuration file:

nano config.local.json

Update these settings:

• openclaw.ws_url: Your OpenClaw server address
• openclaw.api_key: Your API key (if required)
• music.library_path: Path to your music files

Step 3: Add Music (Optional)

# Copy MP3 files to music directory
cp /path/to/your/music/*.mp3 /home/pi/Music/

# Or download sample music
# (Ensure you have rights to the music)

Step 4: Test

# Run in demo mode first
./venv/bin/python3 main.py --mode demo

# Or run in test mode
./venv/bin/python3 main.py --mode test

Step 5: Run

# Start the service
sudo systemctl start voice-assistant

# Or run manually
./start.sh

🎤 Voice Commands

Hotword

First, say the hotword to activate:

• English: "Hey Osiris"
• Mandarin: "你好 Osiris"

General Commands

English	Mandarin	Description
"Hello"	"你好"	Greeting
"What time is it?"	"现在几点？"	Get current time
"How are you?"	"你好吗？"	Greeting response
"Ask Claw: [question]"	"问 Claw：[问题]"	Ask OpenClaw

Music Commands

English	Mandarin	Description
"Play [song name]"	"播放 [歌曲名]"	Play music
"Play music"	"播放音乐"	Play any music
"Pause"	"暂停"	Pause playback
"Resume"	"继续"	Resume playback
"Stop"	"停止"	Stop playback
"Next"	"下一首"	Next track
"Previous"	"上一首"	Previous track
"Volume up"	"音量大"	Increase volume
"Volume down"	"音量小"	Decrease volume

🔧 Troubleshooting

Microphone Not Working

# Check if microphone is detected
arecord -l

# Test recording
arecord -d 3 test.wav
aplay test.wav

# Check volume levels
alsamixer
# Press F4 to see capture levels
# Use arrow keys to adjust

No Sound Output

# Check audio output
speaker-test -t wav

# Set default output
alsamixer
# Press F6 to select output device

Hotword Not Detecting

1. Check microphone sensitivity:

   alsamixer
   # Adjust capture levels
   

2. Reduce background noise

3. Speak clearly and closer to microphone

4. Adjust sensitivity in config:

   {
     "speech": {
       "hotword_sensitivity": 0.6  // Higher = more sensitive
     }
   }
   

Music Not Playing

# Check if files are in correct location
ls -la /home/pi/Music/

# Verify file format (MP3, WAV, OGG, FLAC)
file /home/pi/Music/song.mp3

# Test playback manually
./venv/bin/python3 -c "from music_player import MusicPlayer; p = MusicPlayer(); p.play(list(p.music_library.values())[0])"

OpenClaw Not Connecting

1. Check network connection:

   ping 192.168.1.100  # Replace with your server IP
   

2. Verify OpenClaw is running:

   # On server
   openclaw status
   

3. Check firewall:

   sudo ufw status
   

📊 Logs

View Live Logs

# Service logs
sudo journalctl -u voice-assistant -f

# Installation logs
cat /var/log/voice-assistant-install.log

# Application logs (if configured)
tail -f /var/log/voice-assistant.log

Debug Mode

# Run with debug logging
./venv/bin/python3 main.py --mode run --log-level DEBUG

🔄 Updates

Update Installation

cd /home/pi/voice-assistant

# Pull latest changes (if using git)
git pull

# Reinstall dependencies
source venv/bin/activate
pip install -r requirements.txt --upgrade

Update Configuration

# Edit local config
nano config.local.json

# Restart service
sudo systemctl restart voice-assistant

🛑 Uninstall

# Run uninstaller
sudo ./uninstall.sh

# Or manually:
sudo systemctl stop voice-assistant
sudo systemctl disable voice-assistant
sudo rm -rf /home/pi/voice-assistant
sudo rm /etc/systemd/system/voice-assistant.service

📚 Additional Resources

• Full Documentation
• Google AIY Voice Kit Docs
• Porcupine Hotword Detection
• OpenClaw Documentation

🆘 Support

For issues or questions:

1. Check the README.md
2. Review logs: sudo journalctl -u voice-assistant
3. Test in demo mode first
4. Ensure all dependencies are installed

---

AI Now Inc - Del Mar Show Demo Unit
Version: 1.0.0
Last Updated: 2026-02-28