Troubleshooting

"command not found: clawdbot"

Cause: ClawdBot not in your PATH.

Fix:

1. Close and reopen terminal
2. Check npm prefix: npm config get prefix
3. Add to PATH: export PATH="$(npm config get prefix)/bin:$PATH"
4. Add that line to your ~/.bashrc or ~/.zshrc

Node.js version error

Cause: ClawdBot requires Node.js 22+.

nvm install 22
nvm use 22
node --version

Permission denied (Linux/macOS)

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g clawdbot

Windows: Installation fails

Recommended: Use WSL2 instead of native Windows.

wsl --install
# Restart, then in Ubuntu:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g clawdbot

QR code won't scan / keeps expiring

• Make sure you're using Node.js, not Bun
• QR codes expire quickly—scan within 30 seconds
• Regenerate: clawdbot channels login
• Check internet connection on both computer and phone

WhatsApp disconnects frequently

• Keep phone connected to stable WiFi
• Check WhatsApp → Linked Devices on phone
• Remove old linked devices
• Ensure phone has WhatsApp running in background

ClawdBot not responding to messages

1. Check gateway: clawdbot gateway status
2. Check if pairing needed: clawdbot pairing list whatsapp
3. Approve if needed: clawdbot pairing approve whatsapp CODE
4. Check API key has credits

Gateway won't start

Check if port is in use:

# macOS/Linux
lsof -i :18789

# Windows
netstat -ano | findstr :18789

Use different port:

clawdbot gateway --port 18790

Gateway crashes on startup

1. Run with verbose: clawdbot gateway --verbose
2. Check for config issues: clawdbot config show
3. Re-run onboarding: clawdbot onboard

"Invalid API key" error

1. Verify key at provider's console
2. Re-set the key: clawdbot config set anthropic_api_key "sk-ant-..."
3. Check for extra spaces in the key

Rate limit errors

• Wait a few minutes and retry
• Upgrade API plan for higher limits
• Use a smaller/faster model

"Insufficient credits" error

Add credits at your provider's billing page:

• Anthropic: console.anthropic.com
• OpenAI: platform.openai.com

Slow responses

• Check API provider status page
• Use a faster model for simple tasks
• Clear conversation history if very long

High memory usage

• Restart gateway: clawdbot gateway restart
• Update to latest version: npm update -g clawdbot
• Limit connected channels if not needed