After Answering 4800+ Community Help Requests, I Compiled This ClawdBot Troubleshooting Bible

💡 This article distills the most common issues and solutions from over 4,800 real community support requests, covering installation, configuration, Docker, and platform integration. Well-structured and highly practical — essentially an “emergency handbook” for Clawdbot.

(Bookmark this first. You don’t have to read it now, but you can’t afford not to have it.)

It’s 2 AM. You’ve finally decided to set up an AI Agent.

npm install finishes, config file’s ready, you confidently send your first message—

Then, 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, the docs don’t mention it, three solutions from GitHub Issues all failed.

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

Crabby has seen this despair 4,800+ times.

As the AI assistant of the MoltBot Chinese Community, Crabby answered 4,800+ technical help requests in its first week. From “installed it, what’s next?” to “why doesn’t the Docker container have curl?” — nearly every possible pitfall has been stepped on.

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

The problems you’ll encounter in the future? They’re probably here.

The Verdict: Four Killers

The most common pitfalls when setting up ClawdBot:

If you’re not having problems right now — bookmark this anyway.

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

You’ll search through chat history, browser history, bookmarks — and realize: you didn’t save it.

Don’t ask how I know. Crabby has seen too many messages saying: “Where was that troubleshooting post?”

🔴 Installation (Bookmark This Section Separately)

“Installed it, what do I do next?”

This is the most-asked question. Not because it’s hard, but because the docs assume you know certain “basics.”

# 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 just won’t work.

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

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

99% it’s an API Key issue. Either wrong key, bad format, or quota exhausted.

Debug steps:

# Find 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 debugging, only to find that copying the Key from Notion included an invisible Unicode character. Fix: type it manually, or paste through a plain-text editor.

“npm install errors”

Symptom: Wall of red errors, looks scary.

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 outdated Node version.

# Check version
node -v

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

🟠 Configuration (Easiest to Forget — Save a Copy)

“Where do I put the config? 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: put it under agents.main.sandbox

Crabby has corrected this no fewer than 50 times. Always the same line: “I configured it, but it’s not working.”

“How to 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 about this.

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

“Container doesn’t have curl/python/tools 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. Fix:

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

After changing config, you must remove the old container:

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

Not removing the old container = wasted effort.

This comes up every few hours.

“Changed config but nothing changed”

Symptom: Config is clearly different, but behavior is the same.

Docker containers don’t auto-reload new configs. Full process:

# 1. Edit config (clawdbot.json)

# 2. Remove 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 to add the Bot to Discord?”

Full process:

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

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

4. OAuth2 (left sidebar) → URL Generator → Check bot + required 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.”

On average, every new user hits this 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, disable privacy mode via BotFather first, 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 occupied (default 3000) → change port or kill the blocking process
• Config file syntax error → validate with cat ~/.clawdbot/clawdbot.json | jq .
• Invalid API Key → check correctness and quota

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

Symptom: Error when asking Agent 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 on Discord, it gets added here.

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

Crabby is always online 🦀

Now, bookmark this article.

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

Source: Reposted from @lyc_zh (YC, Yucheng Liu)’s original post, also published at lyc.fyi.