Moltbot Troubleshooting Guide

Use this checklist to fix the most common issues after installation.

Tired of debugging?

Let our experts handle the installation for you via 1-on-1 remote setup.

Get Pro Setup ($199)

BOT_COMMAND_INVALID (Telegram)

This happens when BotFather has no command list. Set commands explicitly:

  1. Open Telegram and chat with @BotFather.
  2. Send /setcommands and choose your bot.
  3. Paste a basic command set, for example:
start - Start the bot
status - Show status
help - Show help

Refusing to bind without auth

The gateway requires an auth token when exposed remotely. Add one to your config:

gateway: {
  auth: {
    token: "YOUR_SECURE_TOKEN"
  },
  bind: "0.0.0.0"
}

Generate a token with:

openssl rand -hex 24

WhatsApp QR fails or disconnects

  • Keep the gateway running 24/7 on a VPS.
  • Use a stable IP and avoid frequent restarts.
  • Rescan the QR code if the session drops.
  • Consider using systemd or launchd to restart on failure.

Docker permissions (VPS)

If Docker runs as root and files are owned by root, fix ownership:

sudo chown -R $USER:$USER ~/.clawdbot ~/.moltbot ~/clawd