How to Install Moltbot Locally on macOS, Linux, and Windows (WSL Guide)

Moltbot (formerly called Clawdbot) is a self-hosted AI automation tool that connects chat platforms like WhatsApp and Telegram to your local machine. It allows you to run commands, search files, generate reports, and automate workflows directly from chat.

Local installation gives you the fastest performance, full system access, and complete control over privacy. You run Moltbot directly on your computer instead of relying on cloud servers or containers.

This guide explains how to install Moltbot locally on macOS, Linux, and Windows using WSL2.

What You Need Before Installing Moltbot

Before you begin, confirm that your system meets these requirements:

Supported Operating Systems

• macOS (Apple Silicon or Intel)
• Linux (Ubuntu, Debian, Fedora, Arch)
• Windows 10 / 11 with WSL2 installed

Software Requirements

• Node.js version 22 or newer
• curl installed
• Stable internet connection

Optional (For Messaging Integration)

• WhatsApp, Telegram, or Discord account
• API key or setup token for AI model provider

Step 1: Check Node.js Version

Moltbot requires Node.js 22 or higher.

Open Terminal (or WSL terminal on Windows) and run:

node -v

If the version is lower than 22 or Node.js is missing, install the latest LTS version from the official Node.js website or your package manager.

Example for Ubuntu:

sudo apt update
sudo apt install nodejs npm

Verify installation again before proceeding.

Step 2: Install Moltbot Using the Official Script

Run the Moltbot installer script directly from your terminal:

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

The installer automatically:

• Detects your operating system
• Downloads required dependencies
• Installs the Moltbot Gateway
• Configures system services

Allow the script to complete without interruption.

Step 3: Launch the Setup Wizard

After installation finishes, Moltbot launches the onboarding wizard automatically.

You will see:

• A security notice explaining that Moltbot can run system commands
• Setup mode selection options

Choose QuickStart unless you need custom configurations.

QuickStart applies safe defaults and speeds up setup.

Step 4: Connect Your AI Model Provider

Moltbot requires an AI model to process commands.

You can use:

• Claude (recommended)
• OpenAI (optional)

Using Claude Setup Token

If you have a Claude subscription:

1. Open a new terminal window.
2. Run:

claude setup-token

3. Copy the generated token.
4. Paste it into the Moltbot setup wizard.

This token remains valid for one year.

Step 5: Connect Messaging Channels

Moltbot can connect to chat platforms for remote control.

WhatsApp Setup

1. Select WhatsApp during channel setup.
2. A QR code appears on the screen.
3. Open WhatsApp on your phone.
4. Navigate to:
   • Settings → Linked Devices → Link a Device
5. Scan the QR code.

Moltbot links your WhatsApp account instantly.

You can also enable Telegram or Discord later from the dashboard.

Step 6: Skip Skills for Initial Setup

The wizard asks whether you want to enable skills.

Skills extend Moltbot’s capabilities but require extra dependencies.

For a clean first install:

• Skip skills configuration
• Enable them later when needed

This keeps the initial setup stable and faster.

Step 7: Start the Moltbot Gateway

After configuration completes, Moltbot installs the Gateway service.

Select the Terminal UI (TUI) launch option.

This opens:

• A terminal chat interface
• A local web dashboard

The gateway starts automatically and continues running in the background.

Step 8: Verify Moltbot Is Working

Send a test message to your connected chat platform.

Example:

“List the files on my desktop.”

You should see:

• The message appear in the terminal
• A response from Moltbot
• The same response in your chat app

If all three update correctly, Moltbot is running successfully.

How Moltbot Runs Locally

When installed locally:

• The Gateway daemon runs in the background.
• It listens for incoming chat messages.
• It executes commands locally using your system permissions.
• It returns results instantly.

The service restarts automatically after system reboot.

Windows Users: Important WSL Setup Notes

If you run Moltbot on Windows:

1. Enable WSL2.
2. Install Ubuntu from Microsoft Store.
3. Open Ubuntu terminal.
4. Follow the same installation steps inside WSL.

Avoid installing Moltbot directly in PowerShell. Always use the Linux terminal inside WSL.

Security Best Practices for Local Installation

Because Moltbot can execute commands, follow these safety rules:

• Do not expose the web dashboard to public internet.
• Avoid granting full disk access unless required.
• Use sandbox mode if available.
• Never share API keys or gateway tokens.
• Restrict WhatsApp allowlist to your phone number only.

For long-term use, consider running Moltbot on a dedicated machine.

When to Choose Local Installation Mode

Local installation works best when:

• You want maximum speed and control
• You prefer running automation on your own machine
• You need direct access to local files and tools
• You value privacy and offline control

If you need public access or 24/7 uptime without keeping your PC running, VPS deployment works better.

FAQs: Common Installation Issues and Fixes

What operating systems support local Moltbot installation?

Moltbot supports macOS, most Linux distributions, and Windows through WSL2. It runs natively on macOS and Linux, while Windows users must install Ubuntu inside WSL before running the installer.

What Node.js version does Moltbot require?

Moltbot requires Node.js version 22 or newer. Check your version using node -v, and upgrade through your package manager or the official Node.js installer if your version is outdated.

The Moltbot command is not recognized after installation. How do I fix it?

Restart your terminal to refresh environment paths or run source ~/.bashrc to reload shell variables. If the command still fails, verify that the installation completed successfully and that the Moltbot binary exists in your system path.

Why is the WhatsApp QR code not scanning or connecting?

Restart the Moltbot gateway to regenerate the QR code and scan it again from WhatsApp’s Linked Devices section. Ensure stable internet connectivity and disable VPNs or firewalls temporarily during pairing.

Moltbot gateway is running but not responding. What should I check?

Restart the gateway using moltbot gateway restart and confirm that no other application blocks the required ports. Also verify that your system meets the minimum Node.js version and memory requirements.

Is local installation safe for daily use?

Local installation is safe when you restrict external access, protect API keys, and avoid exposing the web dashboard publicly. Running Moltbot on a dedicated user account or sandbox mode further improves security.

Can I move from local installation to VPS or NAS later?

Yes, you can migrate anytime by installing Moltbot on a VPS or NAS and reconnecting your messaging channels. Back up any configuration or workflow files before switching environments to avoid data loss.

Local installation provides the fastest and most flexible way to run Moltbot. It gives you complete ownership of data, system access, and automation workflows without relying on cloud infrastructure.

Once configured properly, Moltbot becomes a powerful personal automation engine that runs quietly in the background and responds instantly from chat.