Debugging OpenClaw: Common Issues & Fixes

Symptom: Running openclaw gives "command not found"

Solutions:

1. Check installation: npm list -g | grep openclaw
2. Verify npm bin directory is in PATH: echo $PATH
3. Try full path: $(npm config get prefix)/bin/openclaw
4. Reinstall with sudo if needed: sudo npm install -g openclaw@latest

Symptom: Cannot install globally due to permissions

Solutions:

1. Fix npm permissions: mkdir -p ~/.npm-global && npm config set prefix '~/.npm-global'
2. Add to PATH in ~/.bashrc or ~/.zshrc: export PATH="~/.npm-global/bin:$PATH"
3. Or use sudo: sudo npm install -g openclaw@latest

Symptom: API calls fail with authentication error

Solutions:

1. Verify API key in config: openclaw config get anthropicApiKey
2. Set API key: openclaw config set anthropicApiKey YOUR_KEY
3. Or use environment variable: export ANTHROPIC_API_KEY=YOUR_KEY
4. Check API key hasn't expired or been revoked

Symptom: openclaw daemon start fails silently

Solutions:

1. Check for existing daemon: openclaw daemon status
2. Check logs: openclaw daemon logs --follow
3. Check port conflicts: lsof -i :3000 (or your configured port)
4. Try restart: openclaw daemon restart

Symptom: Daemon crashes after some time

Solutions:

1. Check memory usage: top or htop
2. Review logs for crash details
3. Reduce conversation context size if memory is low
4. Consider using systemd for auto-restart

Symptom: Bot is online but doesn't respond to messages

Solutions:

1. Verify MESSAGE CONTENT INTENT is enabled in Discord Developer Portal
2. Check bot has "Read Messages" and "Send Messages" permissions
3. Verify daemon is running: openclaw daemon status
4. Check logs: openclaw daemon logs

Symptom: Cannot set up Telegram webhook

Solutions:

1. Use polling mode for local development: set mode: "polling" in config
2. For webhook, verify URL is publicly accessible
3. Use ngrok for testing: ngrok http 3000
4. Check Telegram bot token is correct

Symptom: AI takes long time to respond

Solutions:

1. Check internet connection
2. Try faster model (claude-3-5-haiku instead of sonnet)
3. Reduce max_tokens setting
4. Use local models via Ollama for privacy