The Ultimate ClawdBot Troubleshooting Guide • Yucheng (YC)'s Blog

(Bookmark this. You may not need it now, but you will.)

It’s 2 AM. You’ve finally committed to setting up an AI Agent.

npm install done, config file written, confidence high—you send your first message.

Silence.

You stare at the screen, refresh, send another message. Still silence. You open the logs—a wall of incomprehensible errors. Stack Overflow has nothing, official docs don’t mention it, three GitHub Issues solutions all failed.

You start regretting: why didn’t you bookmark that troubleshooting guide you scrolled past?

Crabby has seen this despair over 4,800 times.

As the AI assistant in the MoltBot Chinese community, Crabby answered 4,800+ support requests in its first week. From “installed it, now what?” to “why doesn’t the Docker container have curl?”—community members have stepped on virtually every possible landmine.

This article is the distilled essence of those 4,800 requests.

Whatever problem you’ll face next, it’s probably in here.

The Bottom Line: Four Major Killers

The most common ClawdBot setup pitfalls:

Symptom	Cause	Frequency
Messages get no response	API Key misconfigured	~90%
Config changes don’t take effect	Wrong nesting / indentation issues	~60%
Same behavior after restart	Docker container not rebuilt	~40%
Nothing works at all	Gateway never started	~30%

If you don’t have a problem right now—bookmark this anyway.

Because at 3 AM when you’re desperately debugging, you won’t remember where to find this article.

You’ll dig through chat histories, search history, browser bookmarks, only to find: you didn’t save it.

Don’t ask how I know. Just know Crabby has seen this message too many times: “Where was that troubleshooting post?”

🔴 Installation (Bookmark This Section Separately)

“Installed it, now what?”

The most frequently asked question. Not because it’s hard, but because the docs assume you know certain “common knowledge.”

# 1. Confirm Gateway is running
clawdbot status

# 2. Configure AI provider (pick one)
clawdbot config set openai.apiKey YOUR_KEY
# or
clawdbot config set anthropic.apiKey YOUR_KEY

# 3. Start
clawdbot gateway start

Common fail:

Copying an API Key with an extra space or newline. Invisible to the eye, but it breaks everything.

”Web page loads fine, but messages get no reply”

Symptom: Interface looks normal, messages disappear into the void.

99% of the time it’s the API Key. Wrong key, bad format, or quota exhausted.

Debugging steps:

# Find the logs
# Mac/Linux
cat ~/.clawdbot/logs/gateway.log | tail -100

# Windows
type %USERPROFILE%\.clawdbot\logs\gateway.log

Look for these keywords: 401, invalid_api_key, insufficient_quota

Real case:

One community member spent two hours only to discover that copying the Key from Notion brought along an invisible Unicode character. Fix: type it manually, or run it through a plain text editor.

”npm install errors”

Symptom: A wall of red errors that look terrifying.

# Universal fix
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Prerequisite: Node version 22+.

Many people get stuck here because they’re using the system’s default old Node version.

# Check version
node -v

# If below 22, upgrade with nvm
nvm install 22
nvm use 22

🟠 Configuration (Easy to Forget—Save a Copy)

“Where does config go? What’s the format?”

Config file location: ~/.clawdbot/clawdbot.json

Core structure:

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "channels": {
    "discord": {
      "botToken": "..."
    }
  },
  "agents": {
    "main": {
      "sandbox": { ... }
    },
    "defaults": { ... }
  }
}

Most common pitfall: wrong nesting level.

❌ Wrong: putting sandbox under agents.defaults.sandbox
✅ Correct: under agents.main.sandbox

Crabby has corrected this at least 50 times. Every time: “I configured it, but it’s not working."

"How do I use a third-party proxy?”

For example, using Antigravity or a self-hosted proxy:

{
  "providers": {
    "anthropic": {
      "apiKey": "your-key",
      "baseUrl": "https://your-proxy.com/v1"
    }
  }
}

Note: Don’t add a trailing slash to baseUrl—some proxies are sensitive to this.

🟡 Docker (Skip If Not Using Docker, But Save It Anyway)

“Container doesn’t have curl/python/the tool I need”

Symptom: Agent says “I don’t have permission” or “command not found.”

The sandbox uses a minimal image by default—many tools aren’t installed. Solution:

{
  "agents": {
    "main": {
      "sandbox": {
        "readOnlyRoot": false,
        "image": "your-custom-image"
      }
    }
  }
}

After changing config, you must delete the old container:

docker rm -f $(docker ps -aq --filter name=clawdbot)
clawdbot gateway restart

No delete = no effect.

This gets asked every few hours. Every time I want to say: if you’d bookmarked this article…

”Changed config but nothing changed”

Symptom: Config clearly changed, behavior stays the same.

Docker containers don’t automatically pick up new configs. Full process:

# 1. Edit config (edit clawdbot.json)

# 2. Delete old container
docker rm -f $(docker ps -aq --filter name=clawdbot)

# 3. Restart Gateway
clawdbot gateway restart

Shortcut: If you only changed AI parameters (not sandbox), just clawdbot gateway restart is enough.

🟢 Platform Integration (Must-Save for Discord/Telegram Users)

“How do I add the Bot to Discord?”

Full process:

Go to Discord Developer Portal
Create Application → Bot (left sidebar) → Reset Token → Copy
Configure:

{
  "channels": {
    "discord": {
      "botToken": "your-token",
      "guildId": "your-server-id"
    }
  }
}

Left sidebar: OAuth2 → URL Generator → check bot + needed permissions → copy link → open to invite

Common pitfall:

Forgetting to enable Message Content Intent. Scroll down on the Bot page and turn on “Message Content Intent.”

Every new user steps on this one. Every. Single. One.

”How to configure Telegram?”

{
  "channels": {
    "telegram": {
      "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
    }
  }
}

Get the token from @BotFather.

Note: If you want the bot to respond in groups, you need to disable privacy mode via BotFather, or @ it in every message.

🔵 Gateway

”Gateway won’t start”

# Check status
clawdbot status

# Check logs (key step)
clawdbot gateway logs --tail 50

# Restart
clawdbot gateway restart

Common causes:

Port conflict (default 3000) → change port or kill the occupying process
Config file syntax error → validate with cat ~/.clawdbot/clawdbot.json | jq .
Invalid API Key → check if key is correct and has quota

”Browser control error: ‘Can’t reach control server’”

Symptom: Agent throws errors when trying to control the browser.

# Confirm Gateway is running
clawdbot status

# Try restarting
clawdbot gateway restart

Final Words

This article will be continuously updated.

Every time Crabby answers a new high-frequency question in Discord, I’ll add it here.

If you hit a pitfall not covered here, come tell us in the MoltBot Chinese Community—your pitfall will help the next person debugging at 3 AM.

Got questions? Come ask in the Discord community anytime. Crabby’s always online 🦀

Now, bookmark this article.

Don’t wait until you need it and can’t find it.