How to Install Moltbot: Step-by-Step Setup Guide for Mac, Windows & Linux (2026)

Hey folks who've been side-eyeing Moltbot from a distance—I spent the past week installing this thing across three different systems, hitting every weird error the docs don't mention, and documenting what actually works versus what breaks mid-setup.

Quick heads-up before we dive in: Moltbot (formerly Clawdbot, rebranded after Anthropic's trademark request in late January 2026) is powerful but comes with real security considerations. In the past few weeks, researchers found hundreds of misconfigured instances exposed to the web, and some security experts have raised legitimate concerns about plaintext credential storage and prompt injection risks.

I'm not here to sell you on whether you should install it. I'm here to show you how to install it correctly if you've already decided to test it—and how to avoid the security footguns that tripped up early adopters.

System Requirements

Here's what you need before starting. These aren't suggestions—skip any of these and you'll hit errors 20 minutes into setup.

Important: Moltbot requires Node.js 22.12.0 or later due to security vulnerabilities in earlier versions. I verified this across all three platforms—trying to run it on Node 20.x causes authentication failures that won't show clear error messages.

Installation Steps

Mac Setup

macOS is the most straightforward path. Here's what worked across M1, M2, and Intel Macs I tested:

Step 1: Install Node.js

If you don't have Node.js 22+ installed, get it from the official Node.js download page. I recommend using the macOS installer rather than Homebrew for this—Homebrew sometimes installs older LTS versions by default.

Verify your installation:

node -v
# Should show v22.12.0 or higher

Step 2: Run the Installer

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

This script:

• Downloads and installs Moltbot globally via npm
• Sets up the CLI in your PATH
• Launches the onboarding wizard

What actually happens here: The installer creates a global npm package and adds the moltbot command to your shell. If you see "command not found" after this, your npm global bin directory isn't in your PATH—run echo $PATH and check if $(npm prefix -g)/bin is listed.

Step 3: Complete Onboarding

The wizard will walk you through:

• AI provider setup (Anthropic API key or OpenAI)
• Workspace configuration
• Channel connections (WhatsApp, Telegram, etc.)
• Gateway daemon installation (launchd service)

I recommend enabling authentication during setup. The wizard prompts for this—don't skip it just to save time.

Step 4: Verify the Gateway is Running

moltbot gateway status

If it shows "no auth configured," go back and run moltbot onboard again to set OAuth or API key authentication.

Windows (WSL2) Setup

Critical first step: Native Windows is not supported. You must use WSL2. I tested on Windows 11 and Windows 10 (build 2004+)—both work identically if WSL2 is properly configured.

Step 1: Install WSL2

If you don't have WSL2 yet, open PowerShell as Administrator and run:

wsl --install

This installs WSL2 and Ubuntu by default. You'll need to reboot after this completes. For detailed WSL2 setup instructions, see Microsoft's official WSL installation guide.

Verify WSL2 is active:

wsl --list --verbose

Your Ubuntu distribution should show "VERSION 2" in the output.

Step 2: Launch Ubuntu and Install Node.js

Open your Ubuntu terminal (search "Ubuntu" in Windows Start menu) and install Node.js. I used the NodeSource repository method:

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

Confirm the version:

node -v
# Must show v22.12.0 or higher

Step 3: Run Moltbot Installer

Inside your WSL2 Ubuntu terminal:

curl -fsSL https://molt.bot/install.sh | bash
exec bash  # Reload shell to recognize new PATH

The exec bash command is crucial—without it, your terminal won't recognize the moltbot command even though it's installed.

Step 4: Complete Onboarding

moltbot onboard --install-daemon

This sets up systemd (WSL2 uses systemd for service management) to run the Gateway automatically.

Common WSL2 Issue I Hit: If you see "systemd is not running," your WSL2 instance might need systemd enabled. Edit /etc/wsl.conf:

sudo nano /etc/wsl.conf

Add these lines:

[boot]
systemd=true

Save, exit, then restart WSL2 from PowerShell:

wsl --shutdown

Reopen Ubuntu and try onboarding again.

Linux Setup

Tested on Ubuntu 24.04 and Debian 12. Both worked identically.

Step 1: Install Node.js

Using NodeSource repository (recommended for getting the latest LTS):

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

Verify:

node -v
npm -v

Step 2: Install Moltbot

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

Step 3: Run Onboarding

moltbot onboard --install-daemon

The daemon installs as a systemd user service, so it starts automatically on boot.

Check daemon status:

systemctl --user status moltbot-gateway

If it's not running, you can manually start it:

systemctl --user start moltbot-gateway

Channel Configuration

This is where most first-time setups break. The docs assume you know how to generate bot tokens and API keys—I'm spelling it out step by step.

WhatsApp Setup

What you need: A phone number that isn't already linked to WhatsApp Web on another device.

Step 1: Initiate Login

moltbot channels login

This generates a QR code in your terminal.

Step 2: Scan with WhatsApp Mobile

Open WhatsApp on your phone → Settings → Linked Devices → Link a Device → Scan the QR code.

Important: WhatsApp sessions persist across reboots because Moltbot stores credentials in ~/.clawdbot/credentials/whatsapp/<accountId>/creds.json. This file contains authentication secrets—if your system gets compromised, attackers have full WhatsApp access.

Telegram Setup

You need a Telegram Bot Token from @BotFather.

Step 1: Create Bot on Telegram

1. Message @BotFather on Telegram
2. Send /newbot
3. Follow prompts to name your bot
4. Copy the API token

Step 2: Configure in Moltbot

Edit your config file or use the wizard:

moltbot configure --section telegram

Paste your token when prompted.

Step 3: Approve First DM

As of January 2026, Moltbot locks down DMs by default (security update in v2026.1.8). When someone first messages your bot, they get a pairing code. Approve it:

moltbot pairing approve telegram <code>

This prevents random users from accessing your bot.

Discord/Slack

Similar token-based setup. Generate bot tokens from Discord Developer Portal or Slack App settings, then add them via:

moltbot configure --section discord
moltbot configure --section slack

Common Errors and Fixes

These are the errors I actually hit, not theoretical edge cases.

Error: "moltbot: command not found"

Cause: npm global bin directory isn't in PATH.

Fix:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For macOS using zsh:

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Error: "Gateway health check failed: no auth configured"

Cause: You skipped authentication setup during onboarding.

Fix:

Run onboarding again and choose OAuth or API key authentication:

moltbot onboard

Don't skip the auth section this time.

Error: "sharp: Please add node-gyp to your dependencies"

Cause: Moltbot's image processing library (sharp) is trying to build from source instead of using prebuilt binaries.

Fix:

Force prebuilt binaries:

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g moltbot@latest

If you still see errors, install build tools:

macOS:

xcode-select --install
npm install -g node-gyp

Linux:

sudo apt-get install build-essential

Error: Port 18789 Already in Use

Cause: Another process is using the default Gateway port.

Fix:

Find what's using the port:

lsof -i :18789

Kill the process or change Moltbot's port:

moltbot gateway --port 19000

Security Configuration (Critical)

Based on the security incidents in late January 2026, here's what you must configure before connecting any messaging channels.

Run Security Audit

Moltbot includes a built-in security audit tool:

moltbot security audit

This checks for:

• Exposed Gateway ports without authentication
• Open DM policies (allows anyone to message your bot)
• Plaintext logging of sensitive data
• File permission issues

Auto-fix common issues:

moltbot security audit --fix

This automatically:

• Tightens DM policies to "pairing" mode
• Enables sensitive data redaction in logs
• Sets proper file permissions (600 for config, 700 for directories)

Restrict Network Exposure

The Gateway binds to localhost (127.0.0.1) by default, which is safe. If you need remote access, use Tailscale instead of exposing ports directly:

moltbot gateway --bind tailnet --token <your-token>

Never do this:

moltbot gateway --bind 0.0.0.0  # Exposes to entire network

Enable Authentication

If you skipped auth during setup, add it now:

moltbot configure --section auth

Choose either:

• Password mode: Requires password for all Gateway connections
• Token mode: Requires bearer token in request headers

For Tailscale Funnel (public access), password mode is mandatory.

Verify Credential Storage

Check file permissions on stored credentials:

ls -la ~/.clawdbot/credentials/

All .json files should show 600 (read/write for owner only). If you see 644 or 755, fix them:

chmod 600 ~/.clawdbot/credentials/**/*.json

What I Learned

Installation is straightforward if you follow the exact Node.js version requirement and don't skip security setup. The biggest gotchas:

1. Node.js version matters. Earlier versions cause silent auth failures.
2. WSL2 on Windows is non-negotiable. Native Windows support doesn't exist and won't be added.
3. Default security is now tighter. January 2026 updates locked down DM access—this is good, but means you need to manually approve first-time senders.
4. Credential files are plaintext. If your host system gets malware, your API keys and bot tokens are exposed.

I run Moltbot in a sandboxed Linux VM for testing. For daily use, I wouldn't install it on my main work machine—the attack surface is too broad for how I work. But if you're testing automation workflows or integrating AI into specific tasks, it works exactly as documented once you get past setup.

We've been watching developers spend hours configuring gateways, editing Markdown files, and debugging authentication—just to get persistent AI working. That's why we built Macaron to deliver the same memory and task execution without the self-hosting overhead. Try running one of your real workflows through Macaron and judge the results yourself. Free to start, no CLI wizard, reversible anytime.