Troubleshooting¶

Common issues and solutions for Skippy.

Startup Issues¶

Window Doesn't Appear¶

Symptoms: Skippy seems to start but no window visible.

Solutions:

Check system tray - Look for the 🍺 icon. Double-click to show window.
Check for errors - Run with console:
```
python skippy.py  # Not pythonw
```
Check logs - Look in logs/error_*.log
Reset position - Window might be off-screen. Delete any saved position state and restart.

Gateway Connection Failed¶

Symptoms: Orange dot instead of green, "CLI mode" message.

Solutions:

Start the gateway:
```
openclaw gateway start
```
Check status:
```
openclaw gateway status
```
Verify config - Ensure OpenClaw is properly configured.
CLI mode works - Orange dot means CLI fallback is active. Skippy still works, just without streaming.

Python/Import Errors¶

Symptoms: Error messages about missing modules.

Solutions:

Install dependencies:

pip install PyQt6 edge-tts sounddevice numpy

For voice features:

pip install faster-whisper SpeechRecognition pyttsx3

Verify Python:
```
python --version  # Should be 3.10+
```

Voice Issues¶

Microphone Not Working¶

Symptoms: "Voice input not available" or no recording.

Solutions:

Check Windows permissions:
Settings → Privacy → Microphone
Enable "Allow apps to access your microphone"
Test microphone:
Open Voice Recorder app
Try recording

Check sounddevice:

import sounddevice as sd
print(sd.query_devices())

Install missing packages:
```
pip install sounddevice numpy
```

"No Speech Detected"¶

Symptoms: Recording works but transcription fails.

Solutions:

Speak louder - Move closer to microphone
Reduce background noise
Check audio level - Windows Sound settings → Input level
Try Google fallback:
```
{ "stt_provider": "google" }
```

Whisper Model Won't Load¶

Symptoms: Stuck on "Loading Whisper model..."

Solutions:

Check disk space - Models need 150MB-3GB
Use smaller model:
```
{ "whisper_model": "tiny" }
```

Reinstall faster-whisper:

pip uninstall faster-whisper
pip install faster-whisper

Check for CUDA issues - If you have a GPU, CUDA might conflict:
```
pip install faster-whisper --force-reinstall
```

TTS Not Speaking¶

Symptoms: 🔊 enabled but no audio.

Solutions:

Check volume - System volume, app volume
Check output device - Correct speakers selected?
Check internet - Edge TTS requires connectivity
Try pyttsx3 fallback:
```
{ "tts_provider": "pyttsx3" }
```

Chat/Response Issues¶

No Response from AI¶

Symptoms: Message sent but nothing happens.

Solutions:

Check connection status - Green/orange dot
Look at status bar - What does it say?
Check CLI directly:
```
openclaw agent --message "Hello"
```
Check logs - logs/debug.log

Response Cut Off¶

Symptoms: Response appears incomplete.

Solutions:

Token limits - Long responses may hit limits
Timeout - CLI has 90s timeout (180s with thinking)
Try again - Network issues can truncate

Streaming Not Working¶

Symptoms: Response appears all at once (not streaming).

Solutions:

Check indicator - ⚡ should be green for streaming
Gateway might not support streaming
CLI fallback active - Check for orange dot
Restart gateway:
```
openclaw gateway restart
```

WhatsApp Sync Issues¶

Messages Not Syncing¶

Symptoms: WhatsApp messages don't appear in Skippy.

Solutions:

Check sync enabled:
Tray menu → 📱 Sync to WhatsApp (checked)
Or config.json: "sync_whatsapp": true
Check WhatsApp channel:
```
openclaw channels
```
Verify session ID - Must match between desktop and WhatsApp

Duplicate Messages¶

Symptoms: Same message appears twice.

Solutions:

Normal for sent messages - You see your message + echo
Restart Skippy - Resets message tracking

Check transcript file for duplicates:

Get-Content "$env:USERPROFILE\.openclaw\agents\main\sessions\skippy-desktop.jsonl" -Tail 10

Performance Issues¶

Slow Responses¶

Symptoms: Long delay before response starts.

Solutions:

Reduce thinking level:
```
{ "thinking_level": "off" }
```
Check network - Run speed test
Disable WhatsApp sync - Reduces processing
Use CLI mode - Sometimes faster than streaming

High Memory Usage¶

Symptoms: Skippy using >500MB RAM.

Solutions:

Whisper model loaded - Large models use GB of RAM
Use smaller model:
```
{ "whisper_model": "tiny" }
```
Restart Skippy - Clears accumulated state

UI Freezes¶

Symptoms: Window unresponsive during operations.

Solutions:

Wait - Some operations take time
Check debug.log for stuck operations

Force close and restart:

Stop-Process -Name pythonw -Force
pythonw skippy.py

Debug Mode¶

Enable Debug Logging¶

Debug logs are always written to logs/debug.log.

View live:

Get-Content "C:\Users\ejb71\SkippyBuddy\logs\debug.log" -Wait

Check Error Logs¶

Get-ChildItem "C:\Users\ejb71\SkippyBuddy\logs\error_*.log" | 
    Sort-Object LastWriteTime -Descending | 
    Select-Object -First 1 |
    Get-Content

View Last Response¶

Get-Content "C:\Users\ejb71\SkippyBuddy\temp\last_response.json" | ConvertFrom-Json | Format-List

FAQ¶

Q: How do I reset Skippy completely?¶

# Stop Skippy
Stop-Process -Name pythonw -Force

# Remove config (will regenerate)
Remove-Item "C:\Users\ejb71\SkippyBuddy\config.json"

# Clear temp files
Remove-Item "C:\Users\ejb71\SkippyBuddy\temp\*" -Force

# Clear logs
Remove-Item "C:\Users\ejb71\SkippyBuddy\logs\*" -Force

# Restart
pythonw skippy.py

Q: Can I run multiple Skippy instances?¶

No, Skippy uses #SingleInstance behavior. Only one window runs at a time.

Q: How do I update Skippy?¶

Pull latest code (if using git)
Or replace files manually
Pip install any new dependencies
Restart Skippy

Q: Where is conversation history stored?¶

~/.openclaw/agents/main/sessions/<session_id>.jsonl

Q: How do I clear conversation history?¶

Start a new session via OpenClaw, or change session_id in config.

Getting Help¶

If issues persist:

Collect logs:
logs/debug.log
logs/error_*.log
temp/last_response.json
Note your config (redact sensitive info)
Describe the issue:
What you tried to do
What happened
What you expected

Check OpenClaw status:

openclaw --version
openclaw gateway status