Clawdbot Troubleshooting: Fixing Common Problems

Last updated: February 2026

Something broke. That’s why you’re here. Let’s fix it.

If you haven’t set up Clawdbot yet, start with our complete setup guide. For Telegram-specific setup help, see the Telegram guide.

I’m going to skip the preamble and get straight to solutions. Find your problem below, try the fix. If it doesn’t work, check the “Still stuck?” section at the bottom.

“Clawdbot won’t start”

Symptom: Gateway fails to launch

You run clawdbot gateway start and… nothing. Or an error.

Check 1: Is Node.js installed and recent enough?

node --version

Need v18 or higher. If it’s old or missing:

# macOS
brew install node@22

# Ubuntu
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

Check 2: Is Clawdbot actually installed?

which clawdbot

Should return a path. If not:

npm install -g clawdbot

Check 3: Is there a config file?

cat ~/.clawdbot/clawdbot.json

If it doesn’t exist or is empty, run clawdbot init.

Check 4: Is the config valid JSON?

Broken JSON is the #1 cause of startup failures. Validate it:

cat ~/.clawdbot/clawdbot.json | python3 -m json.tool

If you see an error, you’ve got a syntax problem. Common culprits: - Missing comma after a line - Extra comma on the last item in a list - Unclosed brackets or braces - Wrong quote characters (use straight quotes, not curly)

Check 5: Is the port already in use?

lsof -i :3000

If something’s already on port 3000, either kill it or change Clawdbot’s port in config.

“Bot doesn’t respond to messages”

Telegram specifically

Check 1: Is the gateway running?

clawdbot gateway status

If it says stopped, start it: clawdbot gateway start

Check 2: Is your bot token correct?

Go to BotFather on Telegram, check your bot’s token. Copy it fresh, paste it into your config. Tokens look like: 123456789:ABCdefGHIjklMNO-pqrsTUVwxyz

Watch for: - Extra whitespace - Wrong token entirely - Token that was regenerated (old one won’t work)

Check 3: Is your user ID in allowedUsers?

Find your Telegram user ID (message @userinfobot). Check it’s in the config:

"allowedUsers": [123456789]

Note: It’s a number, not a string. No quotes around it.

Check 4: Did you start the bot?

Open your bot in Telegram and tap “Start” or send /start. Bots can’t message you first.

Check 5: Check the logs

clawdbot gateway logs

Look for errors mentioning Telegram, authentication, or your user ID.

WhatsApp specifically

Check 1: Is the session linked?

clawdbot whatsapp status

If disconnected, re-link:

clawdbot whatsapp link

Scan the QR code with your phone (WhatsApp → Settings → Linked Devices).

Check 2: Phone still connected?

WhatsApp Web sessions can drop if your phone loses connection. Make sure your phone has internet and WhatsApp is running.

“AI responses are wrong/weird/dumb”

Symptom: Bot responds but says strange things

Check 1: Is the workspace path correct?

In your config, check the workspace path:

"workspace": "~/clawd"

Does that directory actually exist? Does it have an AGENTS.md file?

ls ~/clawd/AGENTS.md

Check 2: Is AGENTS.md readable?

The AI reads this file for instructions. If it’s empty or missing, the AI has no guidance.

cat ~/clawd/AGENTS.md

Should contain clear instructions about how the AI should behave. Not sure what Clawdbot is or how it works? Read What is Clawdbot first.

Check 3: Is the model actually connected?

Sometimes API keys expire or get revoked.

clawdbot models list

Should show your model as available. If not, re-add your API key:

clawdbot configure --section models

Check 4: Are you hitting context limits?

Very long conversations can confuse AI. Try starting fresh with “forget the previous conversation” or starting a new chat.

“Authentication errors”

“Unauthorized” or “Invalid API key”

Your AI model credentials are wrong or expired.

Anthropic: 1. Go to console.anthropic.com 2. Check your API key is active 3. If using Max subscription, re-run OAuth: bash clawdbot models auth setup-token --provider anthropic

OpenAI: 1. Check platform.openai.com 2. Verify billing is active 3. Regenerate API key if needed

“OAuth error” or “Refresh token expired”

Tokens expire. Re-authenticate:

Google (Gmail/Calendar):

gog auth login

Follow the browser prompts.

Anthropic Max:

clawdbot models auth setup-token --provider anthropic

“Email/Calendar not working”

Gmail won’t connect

Check 1: Is gog installed?

gog --version

If not: brew install gog (macOS) or see gog docs

Check 2: Are you authenticated?

gog auth status

If not logged in:

gog auth login

Check 3: Is the account correct?

If you have multiple Google accounts, specify which one:

gog gmail messages search "test" --account your@email.com

Check 4: API enabled in Google Cloud?

Gmail API might need enabling: 1. Go to Google Cloud Console 2. Find your project 3. APIs & Services → Enable APIs 4. Search for “Gmail API” and enable it

Same for Calendar API if calendar isn’t working.

Calendar says “API not enabled”

Follow check 4 above, but enable “Google Calendar API” instead.

“Gateway keeps crashing”

Symptom: Starts then stops

Check 1: Look at the crash reason

clawdbot gateway logs | tail -50

The error message usually tells you what’s wrong.

Common crashes:

“Cannot find module…” — Dependency issue. Try reinstalling:

npm install -g clawdbot --force

“EADDRINUSE” — Port already in use. Either kill the other process or change ports.

“JavaScript heap out of memory” — Rare, but increase Node memory limit:

export NODE_OPTIONS="--max-old-space-size=4096"
clawdbot gateway start

Crashes after running for a while — Could be a memory leak or API issue. Check if it’s related to specific actions (sending email, browsing web, etc.)

If it crashes repeatedly

Set up auto-restart. If you’re using launchd (macOS) or systemd (Linux), enable KeepAlive/Restart. See the setup guide for service configuration.

“Can’t send emails”

AI drafts but won’t send

Check 1: Is send permission enabled?

In your gog config, ensure send capability is allowed:

gog auth status

Should show Gmail scopes including send.

Check 2: Does your AGENTS.md allow sending?

The AI might be following instructions that require approval. Check for lines like: - “Never send emails without approval” - “Draft only, don’t send”

Check 3: Try manually

gog gmail send --to "your@email.com" --subject "Test" --body "Testing" --account your@email.com

If this fails, it’s a gog/Gmail issue, not Clawdbot.

“Voice/TTS not working”

No audio output

Check 1: Is TTS configured?

In your config, you need:

"tts": {
  "provider": "elevenlabs",
  "apiKey": "your-key-here",
  "voiceId": "voice-id-here"
}

Check 2: Is the API key valid?

Go to elevenlabs.io, check your API key and remaining credits.

Check 3: Does the voice ID exist?

Voice IDs can be wrong or deleted. Find valid IDs in your ElevenLabs dashboard.

“Everything was working, now it’s not”

Sudden breakage after it was fine

What changed?

Something changed. Think about: - Did you update Clawdbot? (npm update -g clawdbot) - Did you edit the config? - Did your API subscription expire? - Did OAuth tokens expire?

Quick recovery attempts:

1. Restart the gateway:

   clawdbot gateway restart

2. Re-authenticate APIs:

   gog auth login
   clawdbot models auth setup-token --provider anthropic

3. Check API billing (seriously, this is often it)

4. Restore previous config:

   cp ~/.clawdbot/clawdbot.json.backup ~/.clawdbot/clawdbot.json
   clawdbot gateway restart

   (Assuming you have backups. You do have backups, right?)

Still Stuck?

If nothing above fixed it:

1. Get detailed logs

DEBUG=* clawdbot gateway start --foreground 2>&1 | tee debug.log

This creates verbose output. Look for obvious errors.

2. Ask the community

Clawdbot Discord has people who’ve seen most problems. Share: - What you’re trying to do - The exact error message - Relevant config (redact API keys!) - What you’ve already tried

3. Check GitHub Issues

github.com/clawdbot/clawdbot/issues — someone might have reported the same bug.

4. Fresh start (nuclear option)

If everything’s hopelessly broken:

# Backup first!
cp -r ~/.clawdbot ~/.clawdbot.old
cp -r ~/clawd ~/clawd.old

# Clean reinstall
npm uninstall -g clawdbot
rm -rf ~/.clawdbot
npm install -g clawdbot
clawdbot init

Then reconfigure from scratch. Annoying but sometimes faster than debugging.

Prevention Tips

To avoid future headaches:

Back up your config before changing it

cp ~/.clawdbot/clawdbot.json ~/.clawdbot/clawdbot.json.backup

Keep Clawdbot updated but not immediately — let others find bugs first

# Check current version
clawdbot --version

# Update when ready
npm update -g clawdbot

Monitor your API accounts — set billing alerts, check usage

Version control your workspace — git commit your AGENTS.md, MEMORY.md, etc.

Something not covered here? Let us know and we’ll add it.