How to Use Clawdbot

Clawdbot is an open-source, self-hosted personal AI assistant that has been described as "a true 24/7 AI employee." Unlike traditional cloud-based AI assistants, Clawdbot runs on your own hardware and integrates deeply with your local computing environment and daily communication tools.

The core philosophy behind Clawdbot is local-first and self-hosted, giving you complete control over your data, privacy, and functionality. Through its unique Gateway architecture, Clawdbot seamlessly embeds into popular chat platforms like WhatsApp, Telegram, Discord, and Slack, enabling a revolutionary "work in chat" experience.

Who Should Use This Guide?

This comprehensive guide is designed for:

• Developers looking to set up a personal AI coding assistant
• Power users who want to automate daily tasks through chat interfaces
• Teams seeking a self-hosted AI solution with full control
• Privacy-conscious users who prefer local-first AI tools

Before installing Clawdbot, ensure your system meets the following requirements. The setup process is straightforward, but having the right environment is crucial for a smooth experience.

Verifying Node.js Installation

Check if Node.js is installed and verify the version:

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

# If not installed, use nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Clawdbot offers multiple installation methods to suit different needs. The official installation script is recommended for most users as it handles all dependencies and configurations automatically.

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

clawdbot --version

wsl --install -d Ubuntu

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

git clone https://clawdbot.you/repo.git
cd clawdbot

./docker-setup.sh

# Build the image
docker build -t clawdbot:local -f Dockerfile .

# Run onboard wizard
docker compose run --rm clawdbot-cli onboard

# Start the Gateway
docker compose up -d clawdbot-gateway

# Using npm
npm install -g clawdbot@latest

# Using pnpm
pnpm add -g clawdbot@latest

# Verify installation
clawdbot --version

After installation, you'll need to configure Clawdbot using the interactive onboard command. This wizard guides you through all essential settings including authentication, channels, and daemon setup.

clawdbot onboard --install-daemon

Configuration Options

During the onboarding process, you'll configure:

# Check Gateway status
clawdbot gateway status

# Verify system health
clawdbot health

# View all status information
clawdbot status --all

clawdbot gateway --port 18789 --verbose

Configuration File Location

Clawdbot stores its configuration in ~/.clawdbot/clawdbot.json. You can manually edit this file to customize advanced settings:

{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

One of Clawdbot's most powerful features is its ability to integrate with multiple chat platforms. This allows you to interact with your AI assistant through familiar interfaces without switching apps.

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing"
    }
  }
}

clawdbot channels login

{
  "channels": {
    "telegram": {
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN"
    }
  }
}

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

{
  "channels": {
    "slack": {
      "enabled": true,
      "appToken": "xapp-...",
      "botToken": "xoxb-..."
    }
  }
}

Clawdbot's pairing system is a crucial security feature that prevents unauthorized access to your AI assistant. By default, the dmPolicy is set to "pairing", which requires manual approval for any new user attempting to interact with your bot.

How Pairing Works

1. A new user sends a direct message to your Clawdbot
2. Clawdbot responds with a pairing code
3. You review the request and approve it using the CLI
4. Once approved, the user can freely interact with Clawdbot

Managing Pairing Requests

# List pending pairing requests for a channel
clawdbot pairing list whatsapp
clawdbot pairing list telegram
clawdbot pairing list discord

# Approve a pairing request with the provided code
clawdbot pairing approve whatsapp ABC123

# List all approved users
clawdbot pairing list --approved

DM Policy Options

Skills are Clawdbot's core extension mechanism. They allow you to define new capabilities for your AI assistant using simple Markdown files. Each skill contains instructions that guide the AI agent on how to perform specific tasks.

Understanding Skill Priority

Clawdbot loads skills in this priority order:

1. Workspace skills: <workspace>/skills/ (highest priority)
2. Local/hosted skills: ~/.clawdbot/skills/
3. Bundled skills: Built-in skills (lowest priority)

Creating a Custom Skill

mkdir -p ~/clawdbot-workspace/skills/my-custom-skill
cd ~/clawdbot-workspace/skills/my-custom-skill

---
name: weather-checker
description: Check current weather for any city using a weather API.
user-invocable: true
metadata: {"clawdbot":{"requires":{"env":["WEATHER_API_KEY"]}}}
---

## Instructions

When the user asks about weather:
1. Identify the city from the user's request
2. Execute: `curl "https://api.weather.com/v1/current?city={city}&key=$WEATHER_API_KEY"`
3. Parse the JSON response and present a friendly summary
4. Include temperature, conditions, and humidity

Installing Community Skills from ClawdHub

ClawdHub is the public skill registry where you can discover and install community-contributed skills.

# Install a skill from ClawdHub
clawdhub install weather-forecast

# Update all installed skills
clawdhub update --all

# Sync local skills to ClawdHub
clawdhub sync --all

Skill Configuration

Configure individual skills in your clawdbot.json:

{
  "skills": {
    "entries": {
      "weather-checker": {
        "enabled": true,
        "apiKey": "your-weather-api-key",
        "config": {
          "defaultUnit": "celsius"
        }
      },
      "unwanted-skill": {
        "enabled": false
      }
    }
  }
}

Gating Mechanism

Use the requires field in skill metadata to ensure skills only load when their dependencies are available:

• requires.bins: Required binary executables (e.g., ["python3", "ffmpeg"])
• requires.env: Required environment variables (e.g., ["API_KEY"])

Voice Interaction

Clawdbot supports natural voice interaction through Voice Wake and Talk Mode, enabling hands-free operation.

Talk Mode Configuration

{
  "talk": {
    "voiceId": "elevenlabs_voice_id",
    "modelId": "eleven_v3",
    "apiKey": "your_elevenlabs_api_key",
    "interruptOnSpeech": true
  }
}

Canvas Visual Workspace

Canvas is a macOS feature that provides an agent-controlled visual workspace. It renders HTML/CSS/JS content and supports Agent-driven UI (A2UI).

# Display the Canvas panel
clawdbot nodes canvas present --node <id>

# Navigate to a URL or local path
clawdbot nodes canvas navigate --node <id> --url "/"

# Execute JavaScript in Canvas context
clawdbot nodes canvas eval --node <id> --js "document.title = 'New Title';"

# Push A2UI content
clawdbot nodes canvas a2ui push --node <id> --text "Hello from A2UI"

Automated Tasks (Cron Jobs)

Schedule automated tasks using Clawdbot's built-in Gateway scheduler. Supports flexible scheduling with at, every, and cron expressions.

# Add a one-time task (runs in 20 minutes)
clawdbot cron add \
  --name "Reminder" \
  --at "20m" \
  --session main \
  --system-event "Reminder: Check your email" \
  --wake now

# Add a daily recurring task
clawdbot cron add \
  --name "Daily Summary" \
  --cron "0 8 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Generate today's summary report" \
  --deliver \
  --channel whatsapp \
  --to "+15551234567"

# List all scheduled jobs
clawdbot cron list

# Remove a scheduled job
clawdbot cron remove <job-id>

Clawdbot's deployment strategy centers around the Gateway component. Whether running locally or in the cloud, the core principle is to keep the Gateway secure while enabling remote access through encrypted tunnels.

Local Deployment

For personal use on your own machine, local deployment offers the fastest and most straightforward experience.

# Start Gateway (daemon mode)
clawdbot onboard --install-daemon

# Or start manually in foreground
clawdbot gateway --port 18789

# Access locally
# Control UI: http://127.0.0.1:18789/
# WebSocket: ws://127.0.0.1:18789

Remote Access Options

ssh -N -L 18789:127.0.0.1:18789 user@remote

clawdbot gateway --tailscale serve

Cloud/Container Deployment

For VPS or cloud environments, Docker Compose provides isolation and portability:

# Quick setup with Docker
./docker-setup.sh

# Or manual steps
docker build -t clawdbot:local -f Dockerfile .
docker compose run --rm clawdbot-cli onboard
docker compose up -d clawdbot-gateway

Since Clawdbot has the ability to execute system commands and access local resources, security configuration is critical. The core principle is: "Access control before intelligence."

Security Audit Tool

Clawdbot includes a built-in security audit command to identify and fix common vulnerabilities:

# Basic security audit
clawdbot security audit

# Deep audit with Gateway probing
clawdbot security audit --deep

# Auto-fix common issues
clawdbot security audit --fix

Core Security Practices

Recommended Security Configuration

{
  "gateway": {
    "bind": "loopback",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-secure-random-token"
    }
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "pairing",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "all",
        "workspaceAccess": "ro"
      },
      "tools": {
        "deny": ["exec", "write", "apply_patch"]
      }
    }
  }
}

"First 60 Seconds" Diagnostic Flow

When encountering issues, run these commands in order:

# 1. Check basic status
clawdbot status

# 2. Full status report
clawdbot status --all

# 3. Probe Gateway connectivity
clawdbot gateway probe

# 4. Run health diagnostics
clawdbot doctor

# 5. Watch logs in real-time
clawdbot logs --follow

Common Issues and Solutions

# Find npm's global prefix
npm prefix -g

# Add to your shell profile (~/.zshrc or ~/.bashrc)
export PATH="$(npm prefix -g)/bin:$PATH"

# Reload your shell
source ~/.zshrc

Debug Mode

Enable runtime configuration overrides without modifying files:

# In chat, enable debug mode first (requires commands.debug: true)
/debug show
/debug set messages.responsePrefix="[TEST]"
/debug reset