Troubleshooting

This guide covers common issues and their solutions.

Diagnostic Commands

Before troubleshooting, gather system information:

# Check OpenClaw status
openclaw status

# Run diagnostics
openclaw doctor

# View recent logs
openclaw logs

Common Issues

Gateway Won't Start

Symptoms: Gateway fails to start or immediately crashes.

Solutions:

1. Check port availability:

   lsof -i :3000

   If the port is in use, either stop the other process or configure a different port.

2. Verify configuration:

   openclaw doctor

3. Check logs for errors:

   openclaw logs --level error

Model API Errors

Symptoms: "API key invalid" or "Rate limit exceeded" errors.

Solutions:

1. Verify API key:

   openclaw models list

2. Check API key configuration:

   openclaw models config

3. Test model connectivity:

   openclaw models test

Channel Connection Issues

Symptoms: Messages not being received or sent.

Solutions:

1. Check channel status:

   openclaw channels status

2. Re-authenticate if needed:

   openclaw channels setup <channel-name>

3. Verify QR code pairing (for WhatsApp):

   openclaw channels qr whatsapp

Memory/Performance Issues

Symptoms: High CPU or memory usage, slow responses.

Solutions:

1. Check session count:

   openclaw sessions list

2. Clear old sessions:

   openclaw sessions clear --older-than 7d

3. Compact memory:

   openclaw memory compact

Getting More Help

If issues persist:

1. Join the Discord community
2. Search GitHub Issues
3. Create a detailed bug report with logs and system info