Moltbot Tutorial: From Zero to First Skill

Alright, so you're the kind of person who sees "self-hosted AI assistant" and thinks "yeah, I can do that" instead of running away. If you've been watching the Moltbot (formerly Clawdbot) chaos unfold over the past month, you're probably wondering: can I actually get this thing running without breaking my setup?

I spent the last two weeks putting Moltbot through real deployment scenarios — not the polished demos you see on social media, but actual installs on different systems, connecting multiple channels, and testing whether skills work when you need them to. Here's what I learned about getting from zero to a working assistant that actually responds when you message it.

This isn't going to be a feature showcase. It's a hands-on walkthrough of the setup process, the spots where things get confusing, and what you need to know before your first conversation actually works.

Prerequisites

Before jumping in, verify you have these basics covered. Moltbot's January 2026 release (v2026.1.24) tightened up some requirements, so even if you ran earlier versions, double-check:

System Requirements:

• Node.js ≥ 22 (check with node --version)
• macOS, Linux, or Windows via WSL2 (native Windows is not officially supported)
• 4GB RAM minimum for basic operation
• Stable internet connection for initial setup

Accounts You'll Need:

• LLM provider API key (Anthropic, OpenAI, or local model)
• At least one messaging platform account (WhatsApp, Telegram, Discord, or Slack)
• Optional: Brave Search API key for web search capabilities

Network Configuration Note: If you're behind restrictive firewalls or enterprise networks, you might hit silent failures during channel setup. I found this the hard way with Telegram — the pairing process failed without error messages because my router was blocking polling connections. Keep a mobile hotspot handy for initial authentication if you run into issues (see the Telegram pairing troubleshooting issue for details).

Quick Install

The fastest path is the official installer script. It handles dependencies and sets up the daemon automatically:

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

This script:

1. Downloads the latest stable release
2. Installs Node dependencies via npm/pnpm
3. Sets up the Gateway daemon (systemd on Linux, launchd on macOS)
4. Configures workspace directories

Alternative: Manual Install via npm

If you prefer manual control or want a specific version:

npm install -g moltbot@latest
# or with pnpm:
pnpm add -g moltbot@latest

Building from Source

For development or custom configurations:

git clone https://github.com/moltbot/moltbot.git
cd moltbot
pnpm install
pnpm ui:build
pnpm build
moltbot onboard --install-daemon

After installation completes, verify everything's ready:

moltbot doctor

This command runs health checks on your installation and flags any missing dependencies or configuration issues. When I first ran this, it caught that I hadn't configured any LLM authentication — which would have led to confusing failures later when the agent tried to respond.

A Quick Reality Check Here

If you're reading this installation guide thinking "this is more infrastructure than I want to manage," we built Macaron for exactly that friction point. Persistent memory, multi-channel support, and skill execution—minus the Node.js setup, workspace backups, or "is the gateway healthy?" monitoring. Try running your real work through it and judge the results yourself. Free to start, no ClawdHub needed, reversible anytime.

Connect Your First Channel

Once the base install is solid, you need at least one communication channel. The onboarding wizard (moltbot onboard) walks through this interactively, but here's what actually happens behind the scenes for each platform.

Telegram Setup

Telegram is the most straightforward for testing because it doesn't require phone linking like WhatsApp:

Step 1: Create a Bot

1. Open Telegram and message @BotFather
2. Send /newbot
3. Choose a name and username (username must end in 'bot')
4. Copy the bot token BotFather provides

Step 2: Configure Moltbot

export TELEGRAM_BOT_TOKEN="your-token-here"
# Or add to ~/.moltbot/moltbot.json:
# "channels": {
#   "telegram": {
#     "botToken": "your-token-here"
#   }
# }

Step 3: Handle DM Security

As of v2026.1.8, Telegram DMs are locked down by default. When you first message your bot, you'll get a pairing code. Approve it with:

moltbot pairing approve --provider telegram <code>

This allowlist system prevents random people from accessing your assistant if your bot becomes discoverable. I initially missed this and spent 10 minutes wondering why my bot wasn't responding — the pairing message was sitting in my chat waiting for approval.

Verification: Send "Hello" to your bot in Telegram. If everything's configured correctly, you should see the agent processing indicator, then a response powered by your LLM.

WhatsApp Setup

WhatsApp uses QR code authentication similar to WhatsApp Web:

Step 1: Run the Onboarding Wizard

moltbot onboard

When prompted, select WhatsApp as your channel. A QR code will appear in your terminal.

Step 2: Link Your Device

1. Open WhatsApp on your phone
2. Go to Settings → Linked Devices
3. Tap "Link a Device"
4. Scan the QR code from your terminal

Step 3: Configure Allowlist

Edit ~/.moltbot/moltbot.json to specify who can message the assistant:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+1234567890"],
      "groups": ["*"]
    }
  }
}

Important: The groups field became an allowlist in recent versions. If you want to use Moltbot in group chats, add specific group IDs or use "*" to allow all.

Runtime Compatibility: Use Node as your runtime if you're running WhatsApp channels. Bun has known compatibility issues with the WhatsApp connection library, which can cause silent failures or disconnects.

Discord Setup

Discord bots require a bit more OAuth configuration:

Step 1: Create Discord Application

1. Visit Discord Developer Portal
2. Click "New Application"
3. Go to "Bot" section and click "Add Bot"
4. Copy the bot token
5. Under OAuth2 → URL Generator, select scopes: bot, applications.commands
6. For permissions, select: Send Messages, Read Message History, Use Slash Commands

Step 2: Configure Moltbot

export DISCORD_BOT_TOKEN="your-token-here"

Or via config file:

{
  "channels": {
    "discord": {
      "botToken": "your-token-here",
      "dm": {
        "policy": "pairing"
      }
    }
  }
}

Step 3: Invite Bot to Server

Use the OAuth2 URL generated in step 1 to invite your bot to a Discord server.

DM vs. Server Usage: By default, DMs use pairing mode (same as Telegram). For server channels, you can configure requireMention: true to make the bot only respond when @mentioned, preventing it from processing every message in active channels.

Run Your First Skill

Once your channel is connected and responding, the real power comes from skills — pre-built tools that extend what Moltbot can do beyond basic conversation.

Understanding the Skills System

Moltbot uses the AgentSkills convention developed by Anthropic. Skills are folders containing a SKILL.md file with instructions that teach the agent how to use specific tools or APIs.

Skill Loading Precedence:

This precedence means you can override bundled skills by creating your own version in a higher-priority location.

Browse Available Skills

The easiest way to discover skills is through ClawdHub, the public skills registry. As of January 2026, there are 565+ community-contributed skills covering everything from infrastructure management to sports tracking.

Popular Categories:

• File Operations: Batch processing, PDF manipulation, image conversion
• Communication: Email automation, Slack integrations, calendar management
• Development: Docker management, kubectl operations, CI/CD integration
• Productivity: Task tracking (Linear, Asana, Todoist), note-taking, time management
• Infrastructure: Proxmox, Portainer, server monitoring

Installing Your First Skill: Web Search

Let's install a practical skill that demonstrates how the system works — the web search capability.

Step 1: Get a Brave Search API Key

1. Visit Brave Search API
2. Sign up for a free tier account (2,000 queries/month free)
3. Generate an API key from your dashboard

Step 2: Configure Moltbot

moltbot configure --section web

This interactive wizard will prompt you for your Brave Search API key and save it to the config file.

Alternative: Manual Configuration

Edit ~/.moltbot/moltbot.json:

{
  "tools": {
    "web": {
      "search": {
        "apiKey": "BSA..."
      }
    }
  }
}

Step 3: Test the Skill

Message your connected channel (WhatsApp/Telegram/Discord):

What are the latest developments in the Moltbot project?

If configured correctly, the agent will:

1. Recognize it needs current information
2. Use the web search tool
3. Fetch recent results via Brave Search API
4. Synthesize a response based on findings

Debugging Failed Searches: Run moltbot health to verify the web tool is properly configured. Common issues include:

• Missing or invalid API key
• Network restrictions blocking Brave Search API
• Agent not having web search in its allowed tools list (check sandbox settings)

Installing Skills from ClawdHub

For more specialized functionality, browse ClawdHub and install additional skills:

# Install the ClawdHub CLI
npm install -g clawdhub

# Browse available skills
clawdhub search "docker"

# Install a specific skill
clawdhub install weird-aftertaste/docker-compose

# Sync all your installed skills
clawdhub sync --all

Installed skills appear in your workspace's skills/ directory and are automatically loaded on the next agent session.

Security Note: Third-party skills execute with your agent's permissions. Always review skill code before enabling, especially skills that interact with infrastructure, APIs, or sensitive data. Skills can execute shell commands, access files, and make network requests.

Creating a Custom Skill

For a hands-on learning experience, create a simple custom skill:

Step 1: Create Skill Directory

mkdir -p ~/.moltbot/skills/hello-world
cd ~/.moltbot/skills/hello-world

Step 2: Write the Skill Definition

Create SKILL.md:

---
name: hello-world
description: A simple test skill that echoes back messages
---

# Hello World Skill

When the user asks you to test the hello-world skill, respond with:
"Hello from your custom skill! The current time is [current time]."

This skill demonstrates that custom skills are loaded and working correctly.

Step 3: Restart the Gateway

moltbot daemon restart

Step 4: Test Your Skill

Message your bot: "Test the hello-world skill"

The agent should recognize the instruction in your custom SKILL.md and respond accordingly.

This basic example demonstrates the skill system's flexibility — more complex skills can include:

• Binary tool requirements (requires.bins)
• Environment variables (requires.env)
• Config dependencies (requires.config)
• Installation scripts (install array)

For production skills, follow the full skill specification to ensure proper dependency management and platform compatibility.

Next Steps

You now have a functioning Moltbot installation with at least one connected channel and working skills. Here's what to explore next:

Security Hardening

The default configuration runs tools on your host system with full permissions. For production use:

Enable Sandboxing:

Edit ~/.moltbot/moltbot.json:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "docker": {
          "setupCommand": "apt-get update && apt-get install -y curl"
        }
      }
    }
  }
}

This runs non-main sessions (groups, channels) in Docker containers, limiting blast radius if malicious input is processed.

Review DM Policies:

moltbot doctor

This flags any risky DM configurations where your bot might accept commands from unauthorized users.

Add More Channels

Moltbot supports multiple channels simultaneously:

• iMessage (macOS only)
• Signal (via Signal CLI)
• Slack (workspace apps)
• Microsoft Teams
• Matrix

Each channel maintains its own session but shares the same underlying memory and context, so conversations can continue across platforms.

Explore the Control Dashboard

Access the web interface for advanced management:

moltbot dashboard

Opens http://127.0.0.1:18789/ where you can:

• View conversation history
• Monitor agent health and token usage
• Configure settings graphically
• Test prompts and responses
• Manage cron jobs and automation

Memory and Context Management

Moltbot maintains persistent memory in:

• USER.md - Your profile and preferences
• MEMORY.md - Long-term facts and context
• memory/ directory - Structured memory storage

Edit these files directly to:

• Add context about yourself or your projects
• Correct misremembered information
• Seed the agent with domain knowledge

Backup Strategy: These files are critical for maintaining continuity. Set up regular backups:

# Manual backup
tar -czf moltbot-backup-$(date +%Y%m%d).tar.gz ~/.moltbot/workspace

# Scheduled via cron
0 2 * * * tar -czf ~/backups/moltbot-$(date +\%Y\%m\%d).tar.gz ~/.moltbot/workspace

Performance Tuning

Monitor and optimize based on usage patterns:

Check Status:

moltbot status --all

Shows token usage, costs (if using paid APIs), active sessions, and system health.

Model Selection: Configure different models for different scenarios:

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-20250514"
  }
}

Sonnet 4 provides the best balance of capability and cost for most use cases. Use Opus 4 for complex reasoning or Haiku 4 for simple responses to reduce costs.

Community Resources

• Official Docs: docs.molt.bot
• GitHub Repository: github.com/moltbot/moltbot
• Discord Community: 8,900+ members sharing skills and troubleshooting
• Skills Registry: clawdhub.com (565+ skills)

What I Learned About Moltbot After Two Weeks

The installation process is surprisingly smooth when you follow the wizard — the complexity comes from understanding how channels authenticate and how the security model works. The shift to pairing-based DM policies in recent versions is the right call from a security perspective, but it's not immediately obvious when you're testing and wondering why messages aren't processing.

Skills are where Moltbot gets interesting. The ability to wire in specialized capabilities through simple markdown instructions is powerful, but requires understanding the precedence system and binary dependencies. I spent an afternoon trying to figure out why a skill wasn't working before realizing it needed a binary that existed on my host but not in the sandboxed Docker container.

The biggest surprise was memory persistence. Unlike stateless ChatGPT conversations, Moltbot actually remembers context across sessions and channels. This makes it genuinely useful for ongoing projects or workflows that span multiple days — but it also means you need to actively manage what gets stored in memory files.

If you're evaluating Moltbot for production use, focus your testing on:

1. Channel reliability under your network conditions
2. Skill execution in sandboxed vs. host mode
3. Memory management at scale
4. API cost monitoring with real usage patterns

The platform is maturing rapidly (60,000+ GitHub stars in under two months), but security research in January 2026 highlighted real risks when instances are exposed without proper authentication. Treat Moltbot as privileged automation infrastructure, not a consumer toy. Run it in isolated environments, enable sandboxing, and audit your DM policies regularly.