Complete Clawdbot Deployment Guide: Installing Your Personal AI Assistant from Scratch

January 27, 2026·Clawdbot, Deployment·deployment, installation, gateway, channels, production, operations

Scope

This article is designed for developers who want to deploy Clawdbot in a production environment, providing a complete path from environment preparation to stable operation. Unlike quick setup, this guide focuses more on maintainability, security, and long-term stability.

Important Security Warning
Clawdbot is a powerful personal AI assistant capable of breaking down ecosystem barriers between different software and having full operational access to your local computer. This powerful capability also brings potential security risks:
Not recommended for direct installation on your main computer with valuable data
Strongly recommended for deployment in isolated environments:
Virtual machines (VMware, VirtualBox, Parallels, etc.)
Standalone servers or VPS
Dedicated low-spec devices (like used Mac mini)
Docker containers
Production environments must have strict security policies and permission boundaries configured
Clawdbot can be thought of as “the fully unleashed version of Claude Code”—it has broader capabilities, and therefore requires more careful security consideration.

Prerequisites and System Requirements

Hardware Requirements

CPU: 4 cores or more (8+ recommended, local large models require more computing power)
Memory: 8GB minimum (16GB+ recommended, 16GB+ required for running large models locally)
Storage: 10GB+ available space (for dependencies, model files, and data persistence)
Network: Stable internet connection (some dependencies may require VPN access)

Software Environment

Node.js: >= 22.0.0 (required, core dependency for CLI and gateway)
Operating System:
- macOS (Intel/Apple Silicon both supported)
- Linux (Ubuntu 20.04+ recommended)
- Windows (WSL2 required, native Windows not recommended)
Permissions: sudo privileges (macOS/Linux) or administrator rights (Windows)

1. CLI Installation and Verification

Method 1: Official One-Click Installation Script (Recommended for Beginners)

This is the fastest and simplest installation method for users who don’t want to deal with details:

# macOS or Linux
curl -fsSL https://clawd.bot/install.sh | bash

# Windows PowerShell
iwr -useb https://clawd.bot/install.ps1 | iex

Important Notes:

Ensure stable network connection; some dependencies require access to foreign services
The script automatically handles all dependency installations
Installation may take several minutes, please be patient

Method 2: Global Package Manager Installation (Recommended for Developers)

# Using npm
npm install -g clawdbot@latest

# Or using pnpm (recommended, faster installation speed)
pnpm add -g clawdbot@latest

Verify Installation

# Check version and help information
clawdbot --help
clawdbot --version

If you encounter a “command not found” issue, check if the global package path is in your PATH, or restart your terminal.

2. Quick Start Guide (5 Minutes to Get Started)

If this is your first time using Clawdbot, follow this quick process:

Step 1: Launch Quick Setup Mode

clawdbot onboard --flow quickstart

Step 2: Accept Risk Disclaimer

The wizard will display a disclaimer. Enter yes to continue (after understanding the risks).

Step 3: Choose AI Model

Recommended for beginners: Claude (most balanced)
Advanced users can choose: GPT-4, local models, etc.

Step 4: Enter API Key

Based on your chosen model, enter the corresponding API Key:

Claude: Anthropic Console
OpenAI: OpenAI Platform

Step 5: Connect Communication Channels

WhatsApp is strongly recommended (simplest configuration):

# After selecting WhatsApp, a QR code will be displayed
# Scan with your phone's WhatsApp to complete the connection

Other options:

Telegram: Requires creating a bot, more complex configuration
Discord: Requires creating an app, suitable for community use

Step 6: Install Skills and Hooks

The wizard will ask whether to install Claude Skill and Hooks:

Beginners should choose default settings
These are AI “mini-app” extension capabilities

Step 7: Start Using

After completion, you will get:

Local chat interface access URL (usually http://127.0.0.1:18789/)
Connected chat platform contact (format: phone number+ (you))

Quick Test:

Send to Clawdbot in WhatsApp/Telegram:
hello please introduce yourself

3. Wizard-Driven Complete Initialization (Recommended for Advanced Users)

Run Complete Wizard

# Complete wizard including background service installation
clawdbot onboard --install-daemon

The wizard will guide you through:

Gateway operation mode selection (local/remote)
Model authentication configuration (OAuth/API Key)
Channel integration setup (WhatsApp/Telegram/Discord, etc.)
Default security policies (DM pairing, permission boundaries)
Background service installation (launchd/systemd)

4. Gateway Configuration and Startup

Configuration File Location

Gateway configuration files are located at:

macOS: ~/Library/Application Support/Clawdbot/gateway.yaml
Linux: ~/.config/Clawdbot/gateway.yaml
Windows (WSL2): ~/.config/Clawdbot/gateway.yaml

Core Configuration Items

# Gateway basic configuration
gateway:
  port: 18789                    # Service port
  host: "127.0.0.1"              # Bind address

# Model configuration
models:
  default: "gpt-4"               # Default model
  providers:
    openai:
      apiKey: "${OPENAI_API_KEY}" # API key (environment variable recommended)

# Channel configuration
channels:
  telegram:
    enabled: true
    botToken: "${TELEGRAM_BOT_TOKEN}"
  whatsapp:
    enabled: false

# Security policies
security:
  requirePairing: true           # DM requires pairing
  allowedUsers: []               # Whitelist users

Startup and Verification

# Check gateway status
clawdbot gateway status

# Start in foreground (for debugging)
clawdbot gateway --port 18789 --verbose

# Health check
clawdbot status
clawdbot health

Access console: http://127.0.0.1:18789/

5. Channel Integration Configuration

Telegram Channel (Recommended for Beginners)

Create Bot Token

# Search for @BotFather in Telegram
# Send /newbot to create a bot
# Get a token like "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

Configure Channel

clawdbot channels login telegram
# Enter Bot Token when prompted

Verify Connection

# Search for your bot in Telegram
# Send /start to test connection

WhatsApp Channel (Recommended for Production)

# Login to WhatsApp (requires QR code scanning)
clawdbot channels login whatsapp

# Check connection status
clawdbot channels status whatsapp

Discord Channel

# Requires creating Discord app and Bot first
clawdbot channels login discord
# Enter Bot Token and server invite link when prompted

6. Security Policy Configuration

DM Pairing Mechanism (Enabled by Default)

# View pending pairing requests
clawdbot pairing list telegram

# Approve pairing
clawdbot pairing approve telegram <pairing-code>

# Deny pairing
clawdbot pairing deny telegram <pairing-code>

Tool Permission Control

# Configure tool permissions in gateway.yaml
tools:
  # Disable high-risk tools
  deny: ["exec", "browser"]

  # Only allow specific tools
  allow: ["web_fetch", "read", "write"]

  # Restrict by provider
  providers:
    openai: ["web_fetch", "read"]
    local: ["exec", "browser"]

User Permission Management

security:
  # Whitelist users (highest priority)
  allowedUsers:
    - "telegram:user123456"
    - "whatsapp:+86138xxxxxxxx"

  # Admin users (more permissions)
  adminUsers:
    - "telegram:admin123456"

7. Production Environment Deployment

Background Service Configuration

macOS (launchd)

# The wizard will automatically create launchd service
# Manual management:
clawdbot gateway install --service-type launchd

# Start service
launchctl load ~/Library/LaunchAgents/com.clawdbot.gateway.plist

# Check status
launchctl list | grep clawdbot

Linux (systemd)

# Install systemd service
clawdbot gateway install --service-type systemd

# Start and enable service
sudo systemctl start clawdbot-gateway
sudo systemctl enable clawdbot-gateway

# Check status
sudo systemctl status clawdbot-gateway

Remote Access Configuration

SSH Tunnel (Recommended)

# Establish tunnel from local machine
ssh -N -L 18789:127.0.0.1:18789 user@remote-server

# Access remote gateway
http://127.0.0.1:18789/

Tailscale (Recommended for Long-term)

# Install Tailscale on server
curl -fsSL https://tailscale.com/install.sh | sh

# Connect to your network
sudo tailscale up

# Configure gateway to listen on all interfaces
# Set host: "0.0.0.0" in gateway.yaml

Data Persistence

# Configure data directory
data:
  # Absolute path, ensure data security
  directory: "/opt/clawdbot/data"

  # Backup configuration
  backup:
    enabled: true
    interval: "24h"
    retention: "7d"

8. Monitoring and Operations

Health Check Script

#!/bin/bash
# health-check.sh

echo "=== Clawdbot Health Check ==="

# Check CLI
if ! command -v clawdbot &> /dev/null; then
    echo "CLI not found"
    exit 1
fi

# Check gateway status
if ! clawdbot gateway status &> /dev/null; then
    echo "Gateway not running"
    exit 1
fi

# Check channel connections
if ! clawdbot channels status &> /dev/null; then
    echo "Some channels may be disconnected"
fi

# Run health check
clawdbot health

echo "All checks passed"

Log Management

# View real-time logs
clawdbot logs --follow

# View specific component logs
clawdbot logs gateway --follow
clawdbot logs channels --follow

# Log rotation configuration
# In gateway.yaml:
logging:
  level: "info"
  rotation:
    maxSize: "100MB"
    maxFiles: 10

Performance Monitoring

# Check resource usage
clawdbot status --verbose

# Monitor gateway performance
curl http://127.0.0.1:18789/metrics

9. Common Troubleshooting

Installation Issues

Issue: npm install -g clawdbot insufficient permissions

# Solution: Use nvm or modify npm global path
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Issue: Node.js version too low

# Use nvm to manage Node.js versions
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Gateway Issues

Issue: Port already in use

# Find process occupying the port
lsof -i:18789  # macOS/Linux
netstat -ano | findstr 18789  # Windows

# Change port or terminate process

Issue: Channel connection failed

# Check network connection
curl -I https://api.telegram.org

# Re-login to channel
clawdbot channels logout telegram
clawdbot channels login telegram

Performance Issues

Issue: Slow response

# Check model configuration
# Consider using local models or faster API endpoints

# Monitor resource usage
top -p $(pgrep clawdbot)

10. Real-World Use Cases

After deployment, Clawdbot can help you complete various complex tasks. Here are some real-world examples:

Content Creation and Generation

# Let AI draw images in chat interface
@clawdbot help me draw a cyberpunk-style cat picture

# Write YouTube scripts
@clawdbot help me write three YouTube video scripts about AI tutorials

Information Collection and Organization

# Collect AI industry news
@clawdbot summarize today's most important AI news into a briefing

# Monitor specific topics
@clawdbot collect Clawdbot-related discussions and updates every morning

Real Task Automation

Overseas users have already created many innovative use cases:

Restaurant Reservation: Automatically query, compare, and book restaurants
Trading Assistance: Users entrust it for cryptocurrency trading (be cautious!)
Batch Operations: Automate repetitive work like file organization, data entry, etc.
Code Development: Write scripts, debug code, deploy applications

Quick Start Experience

Find Clawdbot contact in your connected chat platform (WhatsApp/Telegram/Discord)
Send a simple command to test connection:
```
hello
```

Try complex tasks:

Help me check today's weather and generate a weather-related image

Skills and Hooks Ecosystem

Clawdbot supports Claude Skill and Hooks system, which can be understood as “mini-apps” that AI can use:

# View available skills
clawdbot skills list

# Install skills
clawdbot skills install calendar-sync
clawdbot skills install email-organizer

# Configure Hooks
clawdbot hooks configure

11. Extensions and Advanced

Skill Plugin Installation

# Install plugins from Clawdhub
clawdbot plugins install email-organizer
clawdbot plugins install code-deployer

# View installed plugins
clawdbot plugins list

Local Large Model Integration

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull model
ollama pull llama3:8b

# Configure local model in gateway.yaml
models:
  default: "ollama:llama3:8b"
  providers:
    ollama:
      endpoint: "http://localhost:11434"