Installation Guide

This guide will help you install and configure Clawdbot from scratch, with the goal of getting you to your first working chat as quickly as possible.

System Requirements

Node.js >= 22 (LTS version recommended)
Operating System:
- macOS (Intel or Apple Silicon)
- Linux (Debian, Ubuntu, CentOS, etc.)
- Windows (requires WSL2)
Optional: pnpm package manager (recommended)

Installation Methods

Method 1: One-line Install Script (Recommended)

Use the official install script that automatically detects your system and installs:

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

Method 2: npm/pnpm Global Install

# Using npm
npm install -g clawdbot
 
# Or using pnpm (recommended)
pnpm add -g clawdbot

Verify Installation

After installation, verify by running:

clawdbot --version

Initial Configuration

Run the Setup Wizard

After installation, run the setup wizard for initial configuration:

clawdbot onboard --install-daemon

The wizard will guide you through:

Authentication Setup
- API Key authentication (direct key input)
- OAuth authentication (recommended for Anthropic)
Platform Selection
- Choose chat platforms to enable (WhatsApp, Telegram, Discord, etc.)
- Configure platform access tokens
Background Service
- Install system daemon
- Configure auto-start on boot

Configuration File

Clawdbot's configuration file is located at ~/.clawdbot/clawdbot.json in JSON5 format.

{
  // Basic settings
  workspace: "~/clawd",
 
  // Channel configuration
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing"
    },
    telegram: {
      enabled: true,
      botToken: "YOUR_BOT_TOKEN"
    }
  },
 
  // Agent configuration
  agents: {
    default: {
      workspace: "~/clawd",
      sandbox: "host"
    }
  }
}

Start the Gateway

After configuration, start the gateway service:

# Run in foreground (for debugging)
clawdbot gateway run
 
# Or run as background service
clawdbot gateway start

Verify Connection

Check status with these commands:

# Basic status check
clawdbot status
 
# Full diagnosis
clawdbot status --all
 
# Gateway health check
clawdbot status --deep

Common Issues

Node.js Version Too Low

If your Node.js version is below 22, upgrade using nvm:

nvm install 22
nvm use 22

Windows Users

Clawdbot requires WSL2 on Windows. Ensure:

WSL2 is enabled
Ubuntu or another Linux distribution is installed
Run Clawdbot within the WSL2 environment

Permission Issues

If you encounter permission issues, check config file permissions:

chmod 600 ~/.clawdbot/clawdbot.json
chmod 700 ~/.clawdbot

Next Steps

Setup Wizard - Learn more about wizard configuration
Dashboard - Manage via web interface
Core Concepts - Understand Clawdbot architecture

Home Wizard