What is ClawBot (MoltBot / OpenClaw) Agent: Installation and Usage Guide

The emergence of OpenClaw, originally introduced as MoltBot and ClawBot, represents a seminal shift in the paradigm of personal artificial intelligence, transitioning from centralized, conversational interfaces toward a decentralized, local-first execution model. This transition, underscored by a rapid ascent in the open-source community that saw the project reach over 60,000 stars on GitHub within its initial launch phase, was catalyzed by a fundamental desire for data residency, low-latency responsiveness, and deterministic tool use. The subsequent rebranding to MoltBot in late January 2026, necessitated by trademark considerations from Anthropic, was framed by its creator, Peter Steinberger, as a natural evolution—a "molting" of the project’s initial shell to accommodate the expansive growth of its agentic capabilities. This report provides an exhaustive technical roadmap for the installation, connection, and advanced utilization of the MoltBot ecosystem, serving as a definitive reference for systems architects, developers, and advanced users seeking to deploy a high-autonomy digital assistant.

Historical Context and the Agentic Revolution

The project’s inception occurred during a period frequently described as the "Agentic Revolution," a time when the focus of large language model (LLM) utility moved from passive text generation to active, multi-step problem solving. MoltBot distinguished itself early by adhering to the "Lobster Way," a philosophical commitment to local orchestration where the "brain" of the AI remains under the user’s direct physical control, even when utilizing cloud-based inference engines like Anthropic’s Claude or OpenAI’s GPT-4. This architecture was designed to mitigate the inherent limitations of proprietary assistants, such as Google Assistant or Siri, which often lack deep filesystem access or persistent, cross-platform memory.
The rebranding event itself provides a unique insight into the volatile intersection of open-source innovation and corporate intellectual property. Following a cease-and-desist request regarding the phonetic similarity between "Clawd" and "Claude," the project adopted the "Molt" branding, which also served to purge the ecosystem of associated cryptocurrency scams that had attempted to leverage the project’s viral success on platforms like Solana. The resulting framework is not merely a chatbot but a sophisticated automation platform that resides in the user’s messaging apps while maintaining full system permissions on their local hardware.

Architectural Foundations: Gateway, Nodes, and Channels

MoltBot operates through a modular three-layer architecture that separates the reasoning engine from the execution environment and the communication interface. Understanding this separation is critical for troubleshooting and for scaling the system across multiple devices.

The Gateway Control Plane

The Gateway serves as the central nervous system of the MoltBot ecosystem. It is a long-running process that exposes a WebSocket control plane on ws://127.0.0.1:18789 and serves a local HTTP interface for the Control UI and WebChat. The Gateway is responsible for session management, model routing, and the scheduling of proactive behaviors via cron jobs and webhooks. It acts as the arbiter between the user’s natural language input and the specific tools or "skills" the agent employs to fulfill a request.

Execution Nodes

While the Gateway handles the logic of orchestration, Nodes represent the "sensory organs" and "hands" of the assistant. These processes allow MoltBot to access local resources such as the file system, browser automation (via headless Chrome), and hardware-specific APIs on macOS, Windows, and Linux. In a remote deployment—such as a Gateway running on a VPS—device-local actions like taking a camera snapshot or triggering a notification occur on the Node process running on the user’s physical hardware. This separation ensures that while the reasoning might happen in the cloud or on a centralized server, the physical execution remains grounded in the user’s immediate environment.

Communication Channels

Channels are the adapters that connect MoltBot to the messaging platforms users already inhabit, including WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and Microsoft Teams. This multi-channel approach allows for a persistent conversational state; a user can initiate a task via WhatsApp on their mobile device and monitor its progress via Telegram on a desktop, with the bot maintaining full context across all surfaces.

Technical Prerequisites and Environment Preparation

The deployment of MoltBot requires a modern computing environment capable of handling high-concurrency Node.js applications and, optionally, local model inference.

Hardware Specification and Optimization

The performance of MoltBot is significantly influenced by the underlying hardware, particularly when using local LLMs or complex browser automation skills. The project has notably driven a surge in Mac Mini sales, as the Apple Silicon unified memory architecture provides an exceptionally efficient environment for AI workloads.

Hardware Category	Recommended Device	Specifications	Strategic Advantage
Default/Standard	Mac Mini M4	16GB Unified Memory, 256GB SSD	Silent operation, tiny footprint, and cost-effective compared to cloud GPU costs.
Power User	Mac Mini M4 Pro	64GB Unified Memory	Supports running large local models (Opus-equivalent) alongside the Gateway.
Budget Linux	BOSGAME B100	16GB RAM, Intel N100, 512GB NVMe	Low-cost entry point for dedicated 24/7 server use.
Ultra-Portable	Raspberry Pi 5	8GB RAM	Suitable for basic gateway routing and light script execution.

A minimum of 4GB of RAM is generally recommended for users intending to utilize the browser automation features, which require running a headless Chromium instance. For those prioritizing privacy and seeking to run models entirely offline, a machine with 24GB to 64GB of RAM is necessary to accommodate larger parameter counts without significant performance degradation.

Software Dependencies

The technical stack for MoltBot is built upon Node.js and the pnpm package manager. Node.js version 22 or higher is a non-negotiable requirement, as the codebase utilizes modern JavaScript features and runtime optimizations unavailable in legacy versions.

1. Node.js: Installation via a version manager like nvm or fnm is strongly recommended to avoid permission conflicts with system-level binaries.
2. pnpm: This is the preferred package manager for its efficient disk usage and faster build times compared to traditional npm.
3. Homebrew: Essential on macOS and Linux for installing peripheral tools and skills such as signal-cli or specific hardware drivers.
4. Java Runtime Environment (JRE): Specifically required (JRE 17 or higher) for the Signal-CLI integration.

Comprehensive Installation Protocols

MoltBot supports a variety of installation methods tailored to different user expertise levels and operational requirements.

The Unified One-Liner Script

For most macOS and Linux users, the quickest path to deployment is the automated installation script. This script detects the operating system, verifies dependencies, and bootstraps the environment.
curl -fsSL https://molt.bot/install.sh | bash
In a Windows environment, this script should be executed within a WSL2 Ubuntu terminal rather than native PowerShell to ensure full compatibility with the Linux-based execution tools.

Platform-Specific Deployment: Windows via WSL2

The project does not currently support a native Windows .exe installer. The recommended path for Windows users is the Windows Subsystem for Linux 2 (WSL2), which provides a high-performance Linux kernel environment on top of Windows.

WSL2 Environment Setup

A successful WSL2 deployment involves several critical steps to avoid common performance and permission pitfalls.

1. Subsystem Installation: Enable the feature using wsl –install in an administrative PowerShell. This installs the default Ubuntu distribution and the necessary virtual machine platform components.
2. Version Verification: It is vital to ensure the distribution is running on Version 2. This can be checked with wsl -l -v. If it displays Version 1, conversion is necessary via wsl –set-version Ubuntu 2, a process that may take several minutes.
3. Native Filesystem Migration: A frequent error for Windows users is attempting to run MoltBot from the /mnt/c/ path. This incurs massive overhead due to the cross-OS filesystem translation. The project must be moved to the WSL native filesystem, typically located at ~/moltbot.
4. Node.js Installation within WSL: Users should avoid using the Windows version of Node.js. Instead, use nvm within the Ubuntu terminal to install the latest LTS or Version 22 specifically:
1. curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
2. source ~/.bashrc
3. nvm install 22.

Developer/Source Installation

For those intending to contribute to the repository or run custom modifications, building from source is required. This method provides the most granular control over the build process and dependencies.

1. Clone the Repository: git clone https://github.com/moltbot/moltbot.git.
2. Install Dependencies: pnpm install.
3. Build the User Interface: pnpm ui:build. This step is crucial as it auto-installs UI dependencies and compiles the assets for the Control Dashboard.
4. Full Project Build: pnpm build.
5. Onboarding: pnpm moltbot onboard –install-daemon. Using the –install-daemon flag ensures that the systemd or launchd service is created, allowing the Gateway to persist after terminal closure.

Docker and Containerized Deployment

For users prioritizing isolation or seeking to deploy on infrastructure like Fly.io, Docker provides a pre-configured environment.

1. Setup Script: The repository includes a ./docker-setup.sh script that automates the image building and initial onboarding.
2. Persistent Storage: When using Docker, it is essential to mount the ~/.clawdbot directory as a volume to ensure that memories, credentials, and configuration persist across container restarts.
3. Docker Compose Override: Advanced users can leverage a docker-compose.override.yml to mount specific credentials, such as a Claude Code CLI session, allowing MoltBot to utilize an existing Claude Pro subscription within the containerized environment.

The Onboarding Wizard: A Step-by-Step Narrative

The moltbot onboard command initiates an interactive dialogue that is the cornerstone of the user experience. This wizard handles the complexity of API key management and service installation.

1. Gateway and Workspace Configuration

The wizard first prompts the user to define the Gateway’s operational mode. For most, "local" is the appropriate choice. If deploying on a cloud server, the user may select "remote," which influences how the system handles tool execution and node pairing. The configuration is stored in ~/.clawdbot/clawdbot.json, which serves as the primary manifest for the assistant’s behavior.

2. Model Selection and Authentication

MoltBot is model-agnostic but highly optimized for Anthropic’s Claude series. The wizard offers a choice between:

1. Claude Opus 4.5: Highly recommended for complex, multi-step tasks due to its superior reasoning and prompt-injection resistance.
2. Claude Sonnet 4.5: A balanced option for routine automation.
3. OpenAI GPT-4o: An alternative for users already integrated into the OpenAI ecosystem.
4. Local Models: Integration with Ollama or LM Studio for users prioritizing absolute privacy.

The authentication phase allows users to either provide a standard API key or utilize an OAuth flow. The OAuth option is particularly attractive as it allows MoltBot to leverage existing personal subscriptions (like Claude Pro), potentially eliminating additional per-token API charges.

3. Channel Selection and Pairing

The wizard provides a checklist of available communication channels. Selecting a channel during onboarding does not automatically log the user in; rather, it prepares the configuration file for the subsequent moltbot channels login step.

Channel-Specific Connection and API Setup

Each communication platform has its own security model and technical requirements for integration.

WhatsApp: The Personal Phone Protocol

MoltBot uses a library called Baileys to emulate a WhatsApp Web session. This allows the bot to act as a "linked device" to a user’s phone number.

1. Login: Execute moltbot channels login –provider whatsapp. A QR code will be rendered in the terminal.
2. Pairing: Open WhatsApp on your mobile device, navigate to "Linked Devices," and scan the QR code.
3. Strategic Note: Because WhatsApp does not have a native "bot" designation, every message sent to the account becomes input for the AI. It is strongly recommended to use a dedicated number for MoltBot to prevent the AI from inadvertently responding to personal messages from friends or family.

Telegram: The BotAPI Standard

Telegram integration is handled via the grammY framework and utilizes the official Telegram Bot API.

1. Bot Creation: Message @BotFather on Telegram and use the /newbot command. You will be prompted to name the bot and choose a username.
2. Token Integration: Once the bot is created, BotFather will provide an API token. This must be pasted into the channels.telegram.botToken section of the clawdbot.json file.
3. Permissions: Unlike WhatsApp, Telegram bots are explicit. You must message the bot first to initiate a session, and the bot cannot "see" messages in groups unless it is given admin permissions or specifically mentioned.

Discord: The Application Portal

Discord integration requires the creation of an "Application" within the Discord Developer Portal.

1. Bot Token: Within the portal, navigate to the "Bot" tab and generate a token. This token is added to the channels.discord.token configuration.
2. Privileged Gateway Intents: For MoltBot to function, the MESSAGE CONTENT INTENT must be enabled in the Developer Portal. Without this, the bot will be "deaf" to the text content of messages.
3. Server Invitation: An OAuth2 invite URL must be generated with permissions for Send Messages, Read Message History, and Attach Files.

Signal: The External CLI Daemon

Signal is the most technically demanding integration, as it requires the signal-cli binary and a Java runtime.

1. Daemon Mode: MoltBot runs signal-cli as a separate background process. The configuration should point to the cliPath of the binary.
2. Account Registration: A separate Signal account/number is mandatory. Signal’s "loop protection" prevents the bot from seeing messages sent from the same account it is running on, meaning you cannot "text yourself" to talk to the bot.
3. Verification: Registration involves an SMS code. In some cases, a CAPTCHA challenge must be solved via the Signal registration website and the resulting token provided to the CLI.

Advanced Configuration: The Lobster Workflow Engine

Lobster is the proprietary workflow shell that defines the "MoltBot Way" of automation. It is a typed, local-first engine that allows the AI to execute multi-step tool sequences as deterministic operations.

Pipeline Structure and Typed Workflows

In traditional AI agents, an LLM might be asked to "research a topic and email the results." The LLM would then improvisatorially call a search tool, then a read tool, then a mail tool. If any step fails, the agent often gets stuck in a loop. Lobster solves this by using YAML-defined pipelines where the structure of the task is rigid, but the content is probabilistic.

Pipeline Component	Function	Strategic Purpose
step: id	Unique identifier for a task segment.	Allows for logging and resuming from a specific failure point.
command	The specific tool or shell script to execute.	Enforces a specific toolchain rather than letting the LLM hallucinate commands.
approval: required	A "Human-in-the-Loop" gate.	Ensures sensitive actions (e.g., deleting a file, sending an email) cannot occur without a cryptographic signature or manual button press.
resumeToken	A persistent identifier for paused tasks.	Allows a workflow to wait for an external event (like a webhook) and resume with full context.

These pipelines are stored as .skill.md or .lobster.yaml files and are published to ClawdHub, a central registry for community-contributed skills.

Interaction Model and Command Analysis

Once MoltBot is operational, the user interacts with it via slash commands and natural language. The system distinguishes between "chat" and "execution" modes.

Core Command Set

Users can control the Gateway’s behavior directly from any connected chat channel using the following commands:

1. /status: Provides a comprehensive health check, including the current session ID, model in use, and activation mode (for groups).
2. /think <level>: Adjusts the reasoning depth (off, minimal, low, medium, high). Higher levels use more tokens but result in more thorough analysis and planning.
3. /models: Refreshes the local model cache and displays available providers. Users can switch models mid-conversation by selecting from the list.
4. /reset: Prunes the current session history. This is vital for managing token costs and preventing context "hallucination" in long-running conversations.
5. /activation mention|always: In group chats, this determines if the bot responds to every message or only those that specifically @mention it.

The /elevated Flag

A unique feature of MoltBot is the ability to temporarily grant the AI higher system permissions. When /elevated on is active, the agent can access restricted directories or execute protected binaries, provided they are in the user-defined allowlist. This state is persisted per-session and is visually indicated in the Control UI.

Security Hardening and Threat Mitigation

The "spiciness" of running an AI agent with shell access necessitates a rigorous security posture. MoltBot provides several mechanisms for hardening the installation.

DM Safety and Pairing Policies

The dmPolicy setting in clawdbot.json is the first line of defense against unauthorized access.

Policy	Behavior	Recommended Use Case
pairing	Unknown senders receive a 6-digit code. The bot ignores them until the owner approves the code.	The default and most secure setting for personal assistants.
allowlist	The bot only responds to specific phone numbers or handles listed in the allowFrom array.	Useful for family bots or small team environments.
open	The bot responds to anyone who messages it.	Not recommended unless the agent is strictly sandboxed in a Docker container.
disabled	Direct messages are ignored; the bot only works in group chats.	High-security corporate environments.

Sandboxing and Isolation

For agents operating in public channels, such as a Discord community or a public Telegram group, MoltBot supports per-session Docker sandboxing. By setting agent.sandbox.mode: "non-main", all tool executions for those sessions are routed into ephemeral containers. This prevents a malicious user from using prompt injection to trick the bot into reading the host machine’s ~/.ssh/ directory or deleting system files.

The Remote Gateway and Tailscale

To securely access a home-based Gateway from the public internet, MoltBot integrates with Tailscale, a mesh VPN.

1. Tailscale Serve: This mode allows the Gateway to be accessible only within the user’s private "tailnet" using HTTPS. It is the recommended way to use the mobile WebChat or Control UI while traveling.
2. Tailscale Funnel: This creates a public HTTPS endpoint for the Gateway. Because this is visible to the entire internet, MoltBot refuses to start Funnel unless a password is set via gateway.auth.mode: "password".

Diagnostic Protocols and Troubleshooting

Despite its robust architecture, the local-first nature of MoltBot means that system updates, network changes, or dependency conflicts can occasionally disrupt service.

The MoltBot Doctor

The primary diagnostic tool is the moltbot doctor command. This utility performs a comprehensive sweep of the environment, checking for:

1. Node.js Integrity: Ensuring the version is v22+ and that critical native modules (like sharp for image processing) are correctly compiled.
2. Configuration Health: Validating the clawdbot.json against the current schema and flagging missing API keys or invalid E.164 phone numbers.
3. Connectivity Probes: Testing the reachability of the model providers (Anthropic, OpenAI) and the status of the messaging channels.

Common Failure Modes and Resolutions

Issue	Root Cause	Remedial Action
Gateway Lock Loop	A previous process crashed and left a stale PID lock file.	The Gateway now compares the Linux process start time to detect PID recycling. Use moltbot gateway restart to clear stale locks.
Signal "Failed to Init HTTP"	Another instance of signal-cli is already bound to the specified port.	Check for background Java processes and ensure signal.httpPort in the config is unique.
WSL2 "Permission Denied"	Files are being accessed across the /mnt/c/ boundary.	Move the project to the native Linux filesystem (/home/user/).
WhatsApp QR Code Fails	The system’s clock is out of sync with the global NTP.	Synchronize the system time. WhatsApp’s authentication is time-sensitive.

Update Management

The assistant is frequently updated. The moltbot update command performs a safe rebase of the local repository, re-installs dependencies, and restarts the Gateway daemon automatically. For developers, the –no-restart flag allows for manual inspection of changes before the service is resumed.

Usage Strategies: Real-World Scenarios

MoltBot’s value is realized through its ability to bridge the gap between AI suggestions and real-world execution.

Scenario A: The Daily Intelligence Briefing

By configuring the cron scheduler, MoltBot can act as a proactive "Calendar Secretary." Every morning at a specified time, the bot can:

1. Scan the user’s Google Calendar and Todoist for upcoming tasks.
2. Pull the latest weather and market movements (e.g., stock alerts or crypto launches).
3. Synthesize this into a "Morning Briefing" sent via WhatsApp or Telegram.
4. Wait for the user’s response to adjust the day’s schedule.

Scenario B: Headless Browser Automation

Using its browser node, MoltBot can perform authenticated web tasks that traditional AI cannot. A user might say, "Check my Hetzner dashboard and alert me if my server usage exceeds 80%." The bot will:

1. Launch a headless Chrome instance.
2. Navigate to the Hetzner portal.
3. Log in (using provided credentials).
4. Extract the relevant data and deliver a formatted report.

Scenario C: The Development Partner

For programmers, MoltBot can be integrated into the Git workflow. A user can send a screenshot of a terminal error via iMessage, and the bot can:

1. Analyze the error.
2. Locate the relevant source file on the local disk.
3. Apply a fix and run the test suite.
4. Commit the change and open a Pull Request—all from the user’s phone.

Conclusion: The Future of Personal AI

The transition from ClawBot to MoltBot signifies more than a name change; it marks the arrival of a mature, production-ready framework for personal automation. By relocating the orchestration layer from the cloud to the user’s own hardware, the project addresses the critical dualities of modern technology: the need for powerful AI reasoning versus the necessity of absolute data privacy.
The success of a MoltBot deployment depends on a deep understanding of its modular architecture—specifically the interplay between the Gateway’s logic and the Node’s execution. As the ecosystem continues to expand through ClawdHub and the Lobster workflow engine, the potential for MoltBot to act as a "24/7 Digital Employee" becomes increasingly tangible. For the professional user, this assistant offers an unprecedented opportunity to regain control over their digital life, turning the "spicy" experiment of agentic AI into a reliable, everyday tool for execution.