Troubleshooting

Common Issues

Installation Problems

Python Version Error

Symptom: SyntaxError or ModuleNotFoundError during installation

Solution:

# Check your Python version
python3 --version

# Must be 3.10 or higher. If not:
# macOS
brew install python@3.11

# Ubuntu/Debian
sudo apt install python3.11

# Windows: Download from python.org

Dependency Installation Fails

Symptom: pip install errors with compilation failures

macOS

# Install Xcode command line tools
xcode-select --install

# Try installation again
pip install -r requirements.txt

Linux

# Install build essentials
sudo apt install build-essential python3-dev

# Fedora
sudo dnf install gcc python3-devel

pip install -r requirements.txt

Windows

# Install Visual C++ Build Tools from:
# https://visualstudio.microsoft.com/visual-cpp-build-tools/

pip install -r requirements.txt

API Key Issues

Invalid API Key

Symptom: AuthenticationError or 401 Unauthorized

Solution:

1. Verify your key at console.anthropic.com
2. Check .env file format:

   # Correct
   ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
   
   # Wrong - has quotes
   ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
   
   # Wrong - has spaces
   ANTHROPIC_API_KEY = sk-ant-api03-xxxxx

Rate Limit Exceeded

Symptom: RateLimitError or 429 Too Many Requests

Solution:

• Wait a few minutes before retrying
• Check your API usage at Anthropic console
• Consider upgrading your API tier

Channel Connection Issues

Telegram Bot Not Responding

1. Verify bot token is correct in .env
2. Send /start to your bot in Telegram
3. Check logs for errors:

   LOG_LEVEL=DEBUG python -m clawdbot

4. Ensure bot has privacy mode disabled (talk to @BotFather)

WhatsApp Connection Failed

Common causes:

• QR code expired - restart and scan again
• Session timeout - delete .wwebjs_auth folder
• Multiple devices - only one active session allowed

# Reset WhatsApp session
rm -rf .wwebjs_auth/
python -m clawdbot
# Scan the new QR code

Discord Bot Offline

1. Check bot token in .env
2. Verify bot is added to your server with correct permissions
3. Enable “Message Content Intent” in Discord Developer Portal:
   • Go to your application
   • Bot → Privileged Gateway Intents
   • Enable “Message Content Intent”

Runtime Issues

High Memory Usage

Symptom: Clawdbot using excessive RAM

Solutions:

• Reduce conversation context length in config
• Restart Clawdbot periodically
• Limit number of active channels

# In .env
MAX_CONTEXT_MESSAGES=50

Slow Responses

Possible causes:

1. API latency: Check Anthropic status page
2. Network issues: Test your connection
3. Large context: Reduce conversation history

# Test API directly
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","max_tokens":100,"messages":[{"role":"user","content":"Hi"}]}'

Unexpected Disconnections

Symptom: Bot disconnects randomly

Solutions:

1. Check network stability
2. Implement auto-restart:

   # Using supervisor or systemd
   # See Platform guides for details

3. Increase timeout settings if available

Debugging Tips

Enable Debug Logging

# Maximum verbosity
LOG_LEVEL=DEBUG python -m clawdbot

# Save to file
LOG_LEVEL=DEBUG python -m clawdbot 2>&1 | tee clawdbot.log

Check Configuration

# Print loaded config
python -m clawdbot --config-check

Test Individual Components

# Test Anthropic connection
python -c "import anthropic; c = anthropic.Anthropic(); print(c.models.list())"

# Test Telegram connection
python -c "import telegram; bot = telegram.Bot('YOUR_TOKEN'); print(bot.get_me())"

Getting Help

If your issue isn’t covered here:

1. Search existing issues: GitHub Issues
2. Ask the community: GitHub Discussions
3. Report a bug: Include:
   • Clawdbot version
   • Python version
   • Operating system
   • Full error message/logs
   • Steps to reproduce