🔧 Troubleshooting

Installation Issues

"npm: command not found"

Node.js isn't installed. Download it from nodejs.org.

"Permission denied" during install

Try installing with sudo:

Or fix npm permissions (recommended):

Gateway Issues

"Gateway failed to start"

Check the logs:

Common causes:

• Missing API key — Check your config.yaml
• Port in use — Another process is using port 3737
• Invalid config — Run clawdbot config validate

"Port 3737 already in use"

Kill the existing process:

Or use a different port in config:

gateway:
  port: 3738

Channel Issues

Telegram bot not responding

• Check your bot token is correct
• Verify your user ID is in allowedUsers
• Make sure the gateway is running: clawdbot gateway status
• Try messaging the bot and checking logs

WhatsApp connection failing

• Ensure you've scanned the QR code
• Check if your phone has internet access
• Try re-linking: delete the session folder and restart

API Issues

"Invalid API key"

• Verify your API key is correct (no extra spaces)
• Check if your API key has credits/billing set up
• Anthropic keys start with sk-ant-

"Rate limit exceeded"

You're sending too many requests. Solutions:

• Wait a few minutes and try again
• Upgrade your API tier
• Enable request caching in config

"Model not found"

The model name might be wrong. Current Anthropic models:

• claude-sonnet-4-20250514 (recommended)
• claude-opus-4-5
• claude-3-5-haiku-20241022

Memory Issues

Assistant forgetting things

• Check that memory.enabled: true in config
• Verify the workspace folder exists
• Check memory files in ~/.clawdbot/memory/

Getting Help

Still stuck? Get help from the community:

• Discord Community — Fastest response
• GitHub Issues — Bug reports
• Full Documentation — Detailed guides

Useful Commands