Skip to main content

Common Issues

Quick solutions for the most frequently encountered ClawBook problems.

AI Not Responding​

Symptoms​

  • Messages sent but no AI response
  • "Processing..." indicator stuck
  • Timeout errors

Solutions​

1. Check AI Provider Status

clawbook-status ai

# Output:
# AI Provider Status
# ==================
# Provider: Anthropic
# Status: ✓ Connected
# Last request: 2 seconds ago
# Response time: 1.2s

2. Verify API Key

  1. Go to Settings → AI Providers
  2. Click Test Connection
  3. If failed, re-enter API key

3. Check Provider Balance

4. Check Rate Limits

tail -f /var/log/openclaw/app.log | grep "rate"

If rate limited, wait or upgrade provider plan.

5. Restart Service

sudo systemctl restart openclaw

WhatsApp Disconnected​

Symptoms​

  • WhatsApp shows "Disconnected" in dashboard
  • Messages not being received
  • QR code not generating

Solutions​

1. Check Phone Status

  • Ensure phone has internet connection
  • WhatsApp app must be running (not killed)
  • Check linked devices limit (max 4)

2. Reconnect

  1. Go to Integrations → WhatsApp
  2. Click Reconnect
  3. Scan new QR code

3. Clear Session

clawbook-whatsapp reset

Then re-scan QR code.

4. Check Logs

tail -f /var/log/openclaw/whatsapp.log

Can't Access Dashboard​

Symptoms​

  • Connection refused
  • Page not loading
  • SSL certificate errors

Solutions​

1. Check Service Status

sudo systemctl status openclaw caddy

Restart if stopped:

sudo systemctl restart openclaw caddy

2. Check Firewall

sudo ufw status
sudo ufw allow 8443/tcp

3. SSL Certificate Issues

If using self-signed cert, browser warning is normal. Click through to proceed.

For Let's Encrypt issues:

clawbook-ssl status
clawbook-ssl renew

4. Check IP/Domain

Ensure you're using the correct URL:

  • https://YOUR_VPS_IP:8443
  • Or https://yourdomain.com

High Memory Usage​

Symptoms​

  • Server slow/unresponsive
  • "Out of memory" errors
  • Services crashing

Solutions​

1. Check Memory Usage

free -h
ps aux --sort=-%mem | head -10

2. Clear Conversation Cache

clawbook-cache clear

3. Reduce Context Window

In Settings → AI Providers:

  • Reduce "Max History Messages" to 10
  • Reduce "Context Token Limit"

4. Restart Services

sudo systemctl restart openclaw postgresql

5. Consider Upgrade

If consistently hitting limits, upgrade your plan.

Slow Responses​

Symptoms​

  • AI takes 10+ seconds to respond
  • Typing indicator shows for long time
  • Timeouts

Solutions​

1. Check Response Times

clawbook-stats performance

# P95 under 5s is normal
# P95 over 10s indicates issues

2. Use Faster Model

Switch from Claude Opus to Claude Sonnet/Haiku:

  1. Settings → AI Providers
  2. Change model to faster option

3. Reduce Context

Smaller context = faster responses:

  • Lower max history messages
  • Clear conversation periodically

4. Check Network

ping api.anthropic.com
curl -w "@/tmp/curl-format.txt" -o /dev/null -s "https://api.anthropic.com/v1/messages"

Telegram Bot Not Working​

Symptoms​

  • Bot appears offline
  • Commands don't respond
  • Messages not delivered

Solutions​

1. Verify Bot Token

  1. Message @BotFather: /mybots
  2. Select your bot → API Token
  3. Compare with ClawBook settings

2. Check Webhook (if using)

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Clear and reset webhook:

curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook"
clawbook-telegram setup-webhook

3. Test Bot Directly

curl "https://api.telegram.org/bot<TOKEN>/getMe"

4. Enable Message Content

If bot in groups isn't responding:

  • @BotFather → /setprivacy → Disable

Discord Bot Offline​

Symptoms​

  • Bot shows offline in Discord
  • Slash commands not appearing
  • No response to messages

Solutions​

1. Check Bot Token

Discord Developer Portal → Your App → Bot → Reset Token if needed.

2. Verify Intents

Must have enabled:

  • ✅ Message Content Intent
  • ✅ Server Members Intent (if needed)

3. Re-invite Bot

Generate new invite URL with correct permissions and re-add to server.

4. Check Gateway Connection

tail -f /var/log/openclaw/discord.log | grep gateway

Backup Failed​

Symptoms​

  • "Backup failed" notification
  • Incomplete backups
  • Cannot restore

Solutions​

1. Check Disk Space

df -h

Free space if needed:

sudo journalctl --vacuum-time=7d
sudo apt autoremove -y
clawbook-cleanup logs --older-than 30d

2. Check Database

sudo -u postgres pg_isready

If not running:

sudo systemctl restart postgresql

3. Manual Backup Test

clawbook-backup create --verbose

Email Notifications Not Sending​

Symptoms​

  • Not receiving alerts
  • Welcome emails not sent
  • Password reset emails missing

Solutions​

1. Check Email Configuration

Settings → Notifications → Email Settings

Verify:

  • SMTP host
  • Port (usually 587 or 465)
  • Username/password
  • From address

2. Test Email

clawbook-email test admin@example.com

3. Check Spam Folder

Add ClawBook sending address to safe senders.

Service Won't Start​

Symptoms​

  • systemctl start openclaw fails
  • Service immediately stops
  • Error on startup

Solutions​

1. Check Logs

sudo journalctl -u openclaw -n 50 --no-pager

2. Check Configuration

clawbook-config validate

# Validates config syntax

3. Check Permissions

ls -la /var/lib/openclaw
# Should be owned by openclaw user

sudo chown -R openclaw:openclaw /var/lib/openclaw

4. Check Dependencies

sudo systemctl status postgresql

Start if stopped.

Quick Diagnostic Commands​

# Overall health check
clawbook-health

# Service status
sudo systemctl status openclaw caddy postgresql

# Recent logs
sudo journalctl -u openclaw -n 100

# Disk space
df -h

# Memory usage
free -h

# Network connectivity
ping -c 3 api.anthropic.com

# Test AI connection
clawbook-ai test

# Restart everything
sudo systemctl restart openclaw caddy postgresql

Still Need Help?​

If these solutions don't resolve your issue:

  1. Search docs: Use the search bar above
  2. Check logs: /var/log/openclaw/
  3. Community: Discord
  4. Support: support@clawbook.io

When contacting support, include:

  • Error messages
  • Steps to reproduce
  • Output of clawbook-health
  • Relevant log snippets