Troubleshooting Common OpenClaw Issues
Quick fixes for the problems you'll actually hit. No fluff.
❌ Agent not responding on Telegram
Check if the gateway is running: `openclaw status`. If stopped, restart with `openclaw gateway restart`. Verify your Telegram bot token is correct in the config.
❌ API key errors / "Unauthorized"
Your AI provider API key may be expired or have insufficient credits. Check your balance on the provider dashboard. Update the key with `openclaw setup`.
❌ High API costs / burning through credits
Switch to a cheaper model for routine tasks. Use Haiku ($0.25/1M tokens) for simple queries and Opus only for complex work. Set up model tiering in your config.
❌ Gateway crashes or restarts frequently
Check logs with `journalctl --user -u openclaw -n 50`. Common causes: out of memory (upgrade VPS), corrupted config (backup and recreate), or Node.js version mismatch.
❌ Voice messages not working
Voice requires a STT provider (Groq Whisper is free) and TTS provider (Edge TTS is free). Check your config has both enabled. Groq API key is required for transcription.
❌ Skills not loading after install
Restart the gateway after installing skills: `openclaw gateway restart`. Check the skill directory exists in your workspace/skills/ folder.
❌ Dashboard shows "502 Bad Gateway"
Your dashboard app isn't running. Check the systemd service: `systemctl --user status your-service`. Build and restart: `npm run build && systemctl --user restart your-service`.
❌ Agent is slow to respond
Large context windows slow responses. Try compacting your conversation history. Use a faster model (Haiku, GPT-4o-mini) for quick tasks. Check your VPS CPU isn't maxed.