Installing Clawdbot on Linux

Clawdbot is fully supported on Linux via CLI (command-line interface), ideal for servers, VPS (Ubuntu, Hetzner), or local devices (Raspberry Pi). It uses Node.js as runtime. Bun is not recommended due to WhatsApp/Telegram compatibility issues. This guide covers Ubuntu/Debian distributions (as of early 2026). Prerequisites: Node.js ≥ 22 (via NodeSource or nvm), npm/pnpm, and Git.

Installation Steps

Step 1: Install Prerequisites

• Update system: sudo apt update && sudo apt upgrade -y
• Install Node.js (v22+ recommended):

  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
  sudo apt install -y nodejs

• Verify: node --version (should show v22.x or higher); npm --version
• For VPS (e.g., Ubuntu 22.04), add swap file to prevent memory issues:

  sudo fallocate -l 2G /swapfile
  sudo chmod 600 /swapfile
  sudo mkswap /swapfile
  sudo swapon /swapfile
  echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Step 2: Install Clawdbot CLI

• Global installation (recommended): npm install -g clawdbot@latest (or pnpm add -g clawdbot@latest)
• From source (optional, developer mode):

  git clone https://github.com/clawdbot/clawdbot.git
  cd clawdbot
  pnpm install
  pnpm build

• Verify: clawdbot --version

Step 3: Run Onboarding and Install Daemon

• Run setup wizard: clawdbot onboard --install-daemon (installs Gateway as user-level systemd service for background operation, even after system restart)
• The wizard will guide you through configuring API keys (Claude/OpenAI), workspace, channels, and skills
• For local models like Ollama, install Ollama first, then specify in configuration

Step 4: Configure Gateway and Channels

• Start Gateway (if not automatic): clawdbot gateway --port 18789 (default port, binds to loopback IP)
• Login to channels (e.g., WhatsApp): clawdbot channels login (scan QR code)
• Configuration stored in ~/.clawdbot/clawdbot.json. Minimal example:

  {
    "agent": {
      "model": "anthropic/claude-opus-4-5"
    }
  }

• For multiple instances, use environment variables: CLAWDBOT_CONFIG_PATH=~/.clawdbot/a.json CLAWDBOT_STATE_DIR=~/.clawdbot-a clawdbot gateway --port 19001

Step 5: Test and Run

• Send test message: clawdbot message send --target <number> --message "hello"
• Dashboard: Access http://127.0.0.1:18789/ (after Gateway starts)
• For VPS, ensure firewall allows necessary ports (e.g., SSH), and use Cloudflare Tunnel to protect exposed ports like 18789

Optional: Docker installation (docs.clawd.bot/install/docker) or Nix mode (declarative config). The entire process typically takes 10-20 minutes, suitable for 24/7 operation on low-cost VPS. For Raspberry Pi, steps are similar but ensure Node.js arm64 support.

Common Issues and Solutions

While Clawdbot is relatively reliable on Linux, users may encounter dependency, permission, service management, and network issues, especially in VPS or headless environments. Below are common problems from GitHub issues, official troubleshooting, and community feedback (as of early 2026), sorted by frequency. Many can be diagnosed with clawdbot doctor. For persistent issues, check logs (~/.clawdbot/logs) or join the official Discord.

Issue	Description	Solution
Node.js version incompatibility	Installation fails with "Node < 22" or dependency errors. Common on older systems or VPS.	Update Node.js to v22+ (use NodeSource script); verify node --version; if using nvm: nvm install 22.
Daemon service not starting or stopping	Gateway installed as systemd service doesn't run or stops after logout (default user service behavior).	Enable lingering: sudo loginctl enable-linger $USER; check status: systemctl --user status clawdbot-gateway; restart: systemctl --user restart clawdbot-gateway.
Port conflicts or exposure risks	Default port 18789 occupied, or VPS exposed without authentication (Shodan scannable).	Specify port: clawdbot gateway --port <new-port>; set firewall (UFW): sudo ufw allow from 127.0.0.1 to any port 18789; use Cloudflare Tunnel for remote access.
HTTP_PROXY ignored	In proxy environments (corporate networks), installation or API calls fail.	Set environment variable: export HTTP_PROXY=http://proxy:port; add proxy settings in config.json; report GitHub issue if persistent.
Channel connection errors (WhatsApp QR expired)	Login fails, QR code doesn't display or expires.	Reset channel: clawdbot channels reset whatsapp; ensure Gateway running; check network (VPS firewall may block); debug: clawdbot channels login --debug.
Memory or performance issues	Crashes on VPS/RPi due to low memory causing OOM.	Add swap file (see installation steps); use low-resource models like Ollama; monitor: htop or free -h; upgrade VPS to at least 2GB RAM.
Docker migration failures	After Docker installation, migrating to native causes config conflicts or state loss.	Backup ~/.clawdbot; uninstall Docker version; re-run clawdbot onboard --install-daemon --force; clean old services: systemctl --user disable clawdbot-gateway.
Dependency installation failures (npm permissions)	npm install reports permission errors or global path issues.	Use sudo npm install -g (not recommended); set npm prefix: npm config set prefix ~/.npm; add to PATH: export PATH=~/.npm/bin:$PATH.
Bun incompatibility	When using Bun runtime, WhatsApp/Telegram bugs occur.	Switch to Node.js (officially recommended); avoid Bun for Gateway.
Compatibility issues after updates	After Linux updates (e.g., kernel), service crashes.	Reinstall: clawdbot gateway install --force; check logs; use Docker container for isolation (docs.clawd.bot/install/docker).

Most issues are system configuration-related. Community feedback indicates VPS users commonly face service persistence issues. If you encounter specific errors, share details for further analysis.