Onboarding

What this is: The full journey from “I just heard about Moltbot” to “I’m messaging my AI from my phone.”

The Flow

Step 1: Install

Pick your poison:

Quick install (recommended):

curl -fsSL https://molt.bot/install.sh | bash

npm/pnpm:

npm install -g moltbot@latest

From source (dev mode):

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install && pnpm build

Step 2: Run the Wizard

moltbot onboard --install-daemon

This is the interactive bit. Answer questions about:

• Where’s your gateway running? (local vs remote)
• How do you want to auth? (OAuth vs API keys)
• What channels? (WhatsApp, Telegram, etc.)
• Install as a service? (yes for “runs on boot”)

Step 3: Verify Install

moltbot status

Should show green checkmarks. Red? The output tells you what to fix.

Step 4: Connect a Channel

WhatsApp:

moltbot channels login

Scan the QR code with your phone.

Telegram/Discord: Provide bot tokens during wizard, or add them manually to config.

Step 5: First Message

Send a DM to your bot. If it’s a fresh contact:

• You’ll get a pairing code
• Approve it: moltbot pairing approve <channel> <code>
• Send your message again
• Bot responds

What Gets Installed

After onboarding:

~/.clawdbot/moltbot.json       # Config
~/.moltbot/                    # State + credentials
~/clawd/                       # Workspace (optional)

System service:

• macOS: ~/Library/LaunchAgents/com.molt.bot.plist
• Linux: ~/.config/systemd/user/moltbot.service

Common First-Time Issues

”Command not found”

The install script should’ve added moltbot to your PATH. If not:

export PATH="$HOME/.moltbot/bin:$PATH"

Add that to .bashrc or .zshrc.

Gateway won’t start

Usually one of:

• Port 18789 already in use
• Node version too old (need 22+)
• Permissions issue

Run moltbot doctor to diagnose.

WhatsApp QR won’t scan

• Make sure you’re on the same network
• Try a different terminal (some don’t render QR codes well)
• Use moltbot dashboard and scan from the web UI instead

Bot doesn’t respond

Check:

1. Is Gateway running? moltbot gateway status
2. Is channel connected? moltbot channels list
3. Did you approve pairing? moltbot pairing list <channel>
4. Is model configured? moltbot status

Skip the Wizard?

Manual setup is totally doable:

1. Create ~/.clawdbot/moltbot.json
2. Add your channel config
3. Set up auth profiles
4. Start Gateway: moltbot gateway

But honestly? The wizard is faster.

Re-running the Wizard

Made a mistake? Start over:

moltbot onboard --reset

This clears wizard state but keeps your credentials/config.

What’s Next

Now that you’re onboarded:

• Lock down security
• Add more channels
• Build custom skills
• Set up automation
• Check out community projects

Stuck? Discord support  is pretty active.