Unleash the Lobster: The Ultimate Guide to Self-Hosting Clawdbot

Reclaim your data and centralize your AI interactions across WhatsApp, Discord, and more—all on your own terms.

• Total Data Sovereignty: Unlike cloud-based assistants, Clawdbot runs entirely on your infrastructure (local or VPS), ensuring your data never leaves your control.

• Unified Omni-Channel Experience: Connect a single AI brain to WhatsApp, Telegram, Discord, Slack, and Signal simultaneously, managing all context in one “Local-first Gateway.”

• Rapid Deployment: This guide allows you to go from zero to a fully functional, self-healing AI instance with advanced pairing security in under 30 minutes.

Clawdbot represents a paradigm shift in personal AI assistants. It is an open-source, self-hosted system that brings the power of LLMs (like Claude Opus and GPT-4) directly to your favorite messaging platforms without a middleman. Whether you are a developer looking for a customizable agent runtime or a privacy enthusiast wanting a secure AI on WhatsApp, Clawdbot provides a seamless, robust solution.

This guide covers everything from the initial Node.js setup to advanced channel configuration, ensuring you have a working “Clawd” (the space lobster assistant) ready to help.

Phase 1: Preparation and Installation

Step 0: Prerequisites & Environment Setup

Before diving into the installation, your environment must be prepared. Clawdbot is built on modern web technologies and requires specific runtime versions.

• Runtime: Node.js Version 22 or higher is strictly required.
• OS: macOS, Linux, or Windows (via WSL2). Native Windows is not supported.
• Hardware: A minimum of 2GB RAM is recommended.

Check your Node version:

Bash

node --version
# Should output: v22.x.x or higher

If you are on an older version or need a fresh install, usage of nvm (Node Version Manager) is highly recommended. For Windows users, you must install WSL2 (Ubuntu) first via PowerShell (wsl --install -d Ubuntu) and run all subsequent commands inside that Linux terminal.

Step 1: Installing the Clawdbot CLI

You have two primary paths for installation: a quick script or a package manager.

Method A: Quick Install (Recommended) This script detects your OS and handles the heavy lifting.

Bash

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

Method B: Global NPM Install If you prefer manual package management:

Bash

npm install -g clawdbot@latest

For those preferring containerization, Clawdbot offers a docker-setup.sh script that builds the image, runs onboarding, and starts the gateway in one go.

Phase 2: Configuration and Core Setup

Step 2: The Onboarding Wizard

Clawdbot features a sophisticated interactive wizard that configures your authentication, models, and initial channels. Run the following to start:

Bash

clawdbot onboard --install-daemon

Critical Decisions during Onboarding:

1. Gateway Mode: Choose Local for your first installation.
2. Authentication: The wizard supports various providers, but an Anthropic API Key is recommended for the best experience with Claude models.
3. Model Selection: anthropic/claude-opus-4-5 offers the highest quality, while sonnet offers a balance of speed and intelligence.
4. Background Service: Select Yes to install Clawdbot as a background daemon (systemd/launchd), ensuring it auto-starts on boot.

Step 3: Starting the Gateway

The Gateway is the central nervous system of Clawdbot. It manages the WebSocket control plane, sessions, presence, and tools.

If you installed the daemon, it is likely running. You can check the status or start it manually for verbose logging:

Bash

clawdbot gateway --port 18789 --verbose

Once running, you can access the Control UI at http://127.0.0.1:18789/. This dashboard provides a visual health check, session monitoring, and a WebChat interface.

Step 4: System Health Verification

Before connecting external channels, ensure the internal systems are green. Run the doctor command to perform a comprehensive diagnostic check of memory, auth validity, and channel health.

Bash

clawdbot doctor

Phase 3: Connecting the World

Step 5: Connecting Your First Channel

Clawdbot supports a multi-channel inbox. You can connect WhatsApp, Telegram, Discord, Slack, Signal, and even iMessage (macOS only).

Option A: WhatsApp (Most Popular) Clawdbot connects via the WhatsApp Web protocol.

1. Run clawdbot channels login.
2. A QR code will generate in your terminal.
3. Open WhatsApp on your phone, go to Linked Devices, and scan the code.

Option B: Discord & The “Error 4014” Fix Discord requires a Bot Token from the Developer Portal. A common hurdle is Error 4014, which indicates missing privileges. To fix this:

1. Go to the Discord Developer Portal.
2. Select your bot and navigate to Bot → Privileged Gateway Intents.
3. Enable Message Content Intent.

Step 6: Security and DM Pairing

Security is paramount when connecting a local script to public messaging platforms. Clawdbot implements a strict Pairing System by default.

When an unknown sender DMs your bot, Clawdbot does not process the message. Instead:

1. It generates a 6-digit code.
2. It replies to the stranger: “Pair with code: 123456”.
3. You (the admin) must verify this request via the CLI:Bashclawdbot pairing approve whatsapp 123456

This adds the user to the allowlist. You can modify these policies (dmPolicy) in ~/.clawdbot/clawdbot.json to be “open” or “disabled” depending on your needs.

Phase 4: Usage and Advanced Features

Step 7 & 8: Interacting and Essential Commands

Once connected, you can chat with Clawd naturally. The system supports rich interactions, including “Thinking Mode” for complex logic puzzles.

Chat Commands:

• /think high: Activates deep reasoning (useful for coding or logic).
• /new: Resets the current conversation context.
• /status: Shows token usage and model costs.

You can also interact via the CLI using clawdbot agent --message "Hello", or use the WebChat on the local dashboard.

Step 9: Beyond the Basics

Now that you have a running instance, you can expand Clawdbot’s capabilities:

• Companion Apps: Install the macOS Menu Bar app or the iOS/Android Nodes for Voice Wake and “Talk Mode” (always-on speech).
• Remote Access: Use Tailscale integration (gateway.tailscale.mode: "funnel") to securely expose your local bot to the internet without port forwarding.
• Skills & Tools: Enable Browser Control (giving Clawd a Chromium instance to browse the web), or create custom skills in ~/clawd/skills.
• Multi-Agent Routing: Configure specific routes to send different channels or groups to isolated agents with distinct personalities defined in SOUL.md.

By following this guide, you have successfully deployed a sovereign AI entity. You are no longer just a user of AI; you are an operator of your own intelligence infrastructure. Welcome to the future of self-hosted AI.