How to Install & Set Up ClawdBot: Complete Step-by-Step Guide

Introduction
System Requirements
Installation Methods
Onboarding Wizard
Channel Configuration
Security and Pairing
Verification and Testing
Advanced Configuration
Troubleshooting
Next Steps

Introduction

Clawdbot is an open-source, self-hosted personal AI assistant that works across multiple platforms including WhatsApp, Telegram, Discord, Slack, and more. Unlike cloud-based alternatives, Clawdbot runs on your own infrastructure, giving you complete control over your data, privacy, and functionality.

This guide will take you from zero to a fully working Clawdbot instance in under 30 minutes. Whether you're deploying on your local machine, a VPS, or containerized environment, this comprehensive setup guide covers everything you need.

System Requirements

Before installing Clawdbot, ensure your system meets these baseline requirements:

Requirement	Details
Node.js	Version 22 or higher (required)
Operating System	macOS, Linux, or Windows (via WSL2)
Memory	Minimum 2GB RAM recommended
Storage	~500MB for installation
Internet	Required for API calls and channel connections

Platform-Specific Notes

Windows Users: Native Windows is not supported. You must use WSL2 (Windows Subsystem for Linux 2). Install it with:

## In PowerShell (Admin)
wsl --install -d Ubuntu

## After restart, open Ubuntu and continue with Linux instructions

macOS Users: No special requirements. Intel and Apple Silicon (ARM) are both supported.

Linux Users: Any major distribution works. Ubuntu 22.04 or later is recommended for best compatibility.

Installation Methods

Clawdbot offers several installation approaches depending on your use case and preferences.

Method 1: Quick Install Script (Recommended)

The quickest way to get started is using the official installer script:

macOS / Linux:

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

Windows (PowerShell in WSL2):

## Inside WSL2 Ubuntu terminal
curl -fsSL https://clawd.bot/install.sh | bash

After installation completes, verify it worked:

clawdbot --version
## Should output the current version number

Method 2: Global npm Install

If you prefer using npm or pnpm directly:

## Using npm
npm install -g clawdbot@latest

## Or using pnpm (faster)
pnpm add -g clawdbot@latest

Verify installation:

clawdbot --version

Method 3: Docker Installation

For containerized deployments or isolated environments:

## Clone the repository
git clone https://github.com/clawdbot/clawdbot.git
cd clawdbot

## Run the setup script (handles everything)
./docker-setup.sh

This script will:

Build the Docker image
Run the onboarding wizard
Start the gateway automatically
Generate access tokens

Open http://127.0.0.1:18789/ and paste the generated token into the Control UI.

Method 4: VPS Deployment

For users deploying on a Linux VPS:

## Update system packages
sudo apt update && sudo apt upgrade -y

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

## Verify Node.js installation
node -v  # Should show v22.x.x

## Install Clawdbot globally
sudo npm install -g clawdbot@latest

Onboarding Wizard

The onboarding wizard is the easiest way to configure Clawdbot completely. It handles model setup, authentication, gateway configuration, and channel connections.

Launch the Wizard

clawdbot onboard --install-daemon

The --install-daemon flag is important: it installs a background service so Clawdbot automatically restarts on boot.

What the Wizard Will Ask

1. Gateway Mode

? Gateway mode:
  ❯ Local (run on this machine)
    Remote (connect to existing gateway)

Choose Local for your first installation.

2. AI Model and Authentication

The wizard will prompt you for your model provider and credentials:

For Anthropic (Claude):

Create an API key at console.anthropic.com
Paste the key when prompted
Recommended: This is the most straightforward method

For OpenAI:

Use an API key from your OpenAI account
Alternative: Use OpenAI Code (Codex) OAuth subscription

For Local Models:

Clawdbot can use local models (like Ollama)
No API keys required—data stays entirely on your device

3. Channel Selection

The wizard asks which messaging platforms you want to connect:

? Which channels would you like to configure?
  ❯ WhatsApp
    Telegram
    Discord
    Slack
    Microsoft Teams
    Signal
    (more options available)

First-time users: We recommend starting with Discord or Telegram as they're quickest to set up.

4. Background Service Installation

? Install as background service?
  ❯ Yes (recommended - auto-starts on boot)
    No (manual start only)

Choose Yes unless you plan to manually manage the service.

Configuration Files Created

After the wizard completes, these configuration files are created:

~/.clawdbot/
├── clawdbot.json           # Main configuration file
├── .env                    # Environment variables (API keys)
├── credentials/
│   ├── oauth.json          # OAuth tokens (if applicable)
│   ├── whatsapp/
│   │   └── default/
│   │       └── creds.json  # WhatsApp session credentials
│   └── telegram/
│       └── auth.json       # Telegram bot tokens
└── agents/
    └── main/
        └── agent/
            └── auth-profiles.json  # AI model authentication profiles

Channel Configuration

Each messaging platform requires specific configuration steps.

WhatsApp Setup

WhatsApp uses QR code authentication:

## Start the pairing process
clawdbot channels login

This generates a QR code that you scan in WhatsApp → Settings → Linked Devices.

Configuration (optional):

Edit ~/.clawdbot/clawdbot.json:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "allowFrom": ["+1234567890"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

Telegram Setup

Telegram requires a bot token created via BotFather:

## Configure Telegram interactively
clawdbot configure --section channels.telegram

Or manually edit ~/.clawdbot/clawdbot.json:

{
  "channels": {
    "telegram": {
      "accounts": {
        "default": {
          "botToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
        }
      }
    }
  }
}

Steps to create a Telegram bot:

Open Telegram and search for @BotFather
Send /newbot
Choose a name and username
Copy the provided token
Paste it into Clawdbot configuration

Discord Setup

Discord requires OAuth2 setup:

## Configure Discord
clawdbot configure --section channels.discord

Manual configuration in ~/.clawdbot/clawdbot.json:

{
  "channels": {
    "discord": {
      "token": "your-discord-bot-token"
    }
  }
}

Steps to create a Discord bot:

Go to Discord Developer Portal
Click "New Application"
Go to "Bot" section and click "Add Bot"
Under TOKEN, click "Copy"
Paste into Clawdbot configuration
In "OAuth2 → URL Generator", select:
- Scopes: bot, applications.commands
- Permissions: Send Messages, Read Message History, Embed Links
Use the generated URL to invite the bot to your server

Restart the gateway after configuration:

clawdbot gateway restart

Slack Setup

Slack requires app configuration through their workspace settings. Add your Slack bot token to:

{
  "channels": {
    "slack": {
      "botToken": "xoxb-your-bot-token"
    }
  }
}

Security and Pairing

Clawdbot implements a security-first approach to prevent unauthorized access.

DM Access Control (Default Pairing Mode)

When DM policy is set to "pairing" (the default), unknown senders receive a short 8-character code:

## List pending pairing requests
clawdbot pairing list whatsapp

## Approve a pairing request
clawdbot pairing approve whatsapp ABC123DE

## Reject a pairing request
clawdbot pairing reject whatsapp ABC123DE

Key features:

Codes expire after 1 hour
Maximum 3 pending requests per channel
Approved senders are stored in credentials directory
Even if someone discovers your bot, they can't use it without approval

Group Chat Protection

For group chats, configure mention requirements:

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "groupChat": {
          "mentionPatterns": ["@clawd", "@mybot"]
        }
      }
    ]
  }
}

The bot only responds when explicitly mentioned with specified patterns.

DM Policy Options

Policy	Behavior
`pairing` (default)	Unknown senders get a code; bot ignores messages until approved
`allowlist`	Unknown senders are blocked; no pairing handshake
`open`	Allow anyone to DM (requires `"*"` in allowlist)
`disabled`	Ignore all inbound DMs

Recommended secure baseline:

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    },
    "telegram": {
      "dmPolicy": "pairing"
    },
    "discord": {
      "dm": { "policy": "pairing" }
    }
  }
}

Verification and Testing

Before using Clawdbot in production, verify everything is working correctly.

Check Overall Status

## Quick status check
clawdbot status

## Expected output:
## Gateway: running (ws://127.0.0.1:18789)
## Auth: configured (anthropic)
## Channels:
##   - whatsapp: ready (linked)
##   - telegram: not configured
##   - discord: not configured
## Sessions: 0 active

Deep Diagnostics

## Perform a deep health check
clawdbot health

## Run diagnostic tests
clawdbot doctor

## View full status with detailed info
clawdbot status --all

## Follow live logs
clawdbot logs --follow

Send Your First Message

Method 1: Via CLI

clawdbot message send --target +1234567890 --message "Hello from Clawdbot!"

Method 2: Via Agent Chat

## Interactive conversation with thinking enabled
clawdbot agent --message "What's the weather today?" --thinking high

Method 3: Via Web UI

Open http://127.0.0.1:18789/ in your browser and use the WebChat interface.

Method 4: Via Messaging Platform

WhatsApp: Send a message to your linked device
Telegram: Send a message to your bot
Discord: Mention your bot in a channel or DM

Advanced Configuration

Model Selection and Failover

Configure which AI models are available:

## View available models
clawdbot models list

## Change model for current session
/model claude-opus-4-5

Configure allowed models in clawdbot.json:

{
  "agents": {
    "defaults": {
      "models": ["anthropic/claude-opus-4-5", "openai/gpt-4-turbo"]
    }
  }
}

Skills and Tools

Enable additional capabilities through skills:

## Configure web search skill
clawdbot configure --section web

## Install skills from ClawdHub
clawdbot skills install <skill-name>

## List enabled skills
clawdbot skills list

Popular skills:

Web search (Brave Search integration)
Browser automation (headless Chrome control)
Email and calendar integration
Developer tools and command execution

Workspace Configuration

Configure the agent workspace where skills and custom instructions live:

{
  "agents": {
    "defaults": {
      "workspace": "~/clawd"
    }
  }
}

Key workspace directories:

AGENTS.md – System prompt and agent configuration
SOUL.md – Personal instructions and preferences
TOOLS.md – Tool configuration and permissions
skills/ – Custom skill definitions

Session Management

Configure how conversations are handled:

## List active sessions
clawdbot sessions list

## View session history
clawdbot sessions history <session-id>

## Reset a session (clear memory)
clawdbot sessions reset <session-id>

Troubleshooting

Common Issues and Solutions

"clawdbot: command not found"

Cause: Node.js or npm PATH issue

Solution:

## Check if installation was successful
npm list -g clawdbot

## Reinstall if needed
npm install -g clawdbot@latest

## Add npm to PATH if using nvm
export PATH="$HOME/.nvm/versions/node/v22.x.x/bin:$PATH"

Gateway fails to start or "unauthorized" error

Cause: Missing or invalid authentication

## Run in verbose mode for detailed logs
clawdbot gateway --port 18789 --verbose

## Check model/auth status
clawdbot models status

## Validate credentials
clawdbot doctor

Bot not responding in Discord/Telegram

Cause: Permissions not configured correctly

## Verify channel configuration
clawdbot status --all

## Reconfigure the channel
clawdbot configure --section channels.discord

## Check if bot has required permissions
## For Discord: Settings → Bot → Scopes & Permissions

"model not allowed" error

Cause: Model not in allowed allowlist

## Check current allowlist
clawdbot config get agents.defaults.models

## Clear or update allowlist
clawdbot configure --section models

WSL2 Node/npm PATH issues

Solution:

## Verify you're using WSL2 Linux versions
which npm  # Should start with /home/, not /mnt/c/

## If pointing to Windows:
## Reinstall Node.js inside WSL2
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Getting Help

When reporting issues, include:

## Generate a safe diagnostic report
clawdbot status --all
clawdbot logs --follow
clawdbot doctor

Paste this information in GitHub issues or the Clawdbot community Discord.

Next Steps

After successful setup, consider these enhancements:

1. Install Companion Apps

macOS Menu Bar App: Instant access from your menu bar
iOS Node: Control Clawdbot from your iPhone
Android Node: Control Clawdbot from your Android device

2. Enable Advanced Features

Voice Wake: Trigger Clawdbot by voice
Talk Mode: Voice conversation support
Browser Control: Automate web interactions
Cron Jobs: Schedule automated tasks

3. Configure Remote Access

Tailscale Integration: Secure remote access
SSH Tunnels: Access from anywhere
Public Gateway: Make bot accessible from internet (use caution)

4. Explore Skills Marketplace

Visit ClawdHub to discover and install:

Integration skills for third-party services
Domain-specific tools for your workflow
Community-contributed extensions

5. Customize Your Agent

Create custom instructions in your workspace:

## Edit agent personality and behavior
nano ~/clawd/AGENTS.md
nano ~/clawd/SOUL.md

## Restart for changes to take effect
clawdbot gateway restart

6. Set Up Multiple Agents

Create separate agents for different use cases:

{
  "agents": {
    "list": [
      {
        "id": "main",
        "workspace": "~/clawd-main"
      },
      {
        "id": "work",
        "workspace": "~/clawd-work"
      }
    ]
  }
}

Conclusion

You now have a fully functional Clawdbot instance ready to serve as your 24/7 personal AI assistant. The setup is just the beginning—the true power emerges as you customize skills, configure access controls, and integrate Clawdbot into your daily workflow.

For detailed documentation, visit docs.clawd.bot

For community support and discussions, join the Clawdbot Discord

Happy automating!