🦞 OpenClaw Setup Guide

Ubuntu Desktop + NVIDIA RTX 3060 + WhatsApp Chat

Running as user clawdbot@ai in /home/clawdbot

Table of Contents

  1. Overview — What is OpenClaw?
  2. Prerequisites
  3. Create the clawdbot User
  4. Install Node.js 22+
  5. NVIDIA RTX 3060 Driver Setup
  6. Install OpenClaw
  7. Run the Onboarding Wizard
  8. Configure OpenClaw
  9. Set Up WhatsApp Channel
  10. Run as a systemd Service (Always-On)
  11. Browser Control (Optional)
  12. Verify and Troubleshoot
  13. Useful Commands Reference

1. Overview — What is OpenClaw?

OpenClaw (formerly Clawdbot) is an open-source personal AI assistant you run on your own machine. It connects to chat platforms you already use — WhatsApp, Telegram, Discord, Slack, Signal, iMessage — and can browse the web, execute shell commands, manage files, run cron jobs, and extend itself with skills/plugins.

Key facts:

2. Prerequisites

Hardware

Accounts & API Keys

Software


npm install -g @anthropic-ai/claude-code
claude setup-token

3. Create the clawdbot User

Create a dedicated system user to run OpenClaw in its own isolated home directory:

# Run as root or with sudo from your admin account
sudo adduser clawdbot --home /home/clawdbot --shell /bin/bash

# Set a password when prompted, or:
sudo passwd clawdbot

# Add clawdbot to useful groups
sudo usermod -aG video,audio,render clawdbot

# (Optional) Allow clawdbot to run systemd user services after logout
sudo loginctl enable-linger clawdbot

Now switch to the clawdbot user for all remaining steps:

su - clawdbot
# You are now clawdbot@ai in /home/clawdbot

4. Install Node.js 22+

OpenClaw requires Node.js 22 or newer. Install via NodeSource:

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

# Verify versions
node --version    # Should be v22.x.x or higher
npm --version     # Should be 10.x+

Alternatively, use nvm (Node Version Manager) for per-user installs without sudo:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc

# Install and use Node 22
nvm install 22
nvm use 22
nvm alias default 22

# Verify
node --version

5. NVIDIA RTX 3060 Driver Setup

The RTX 3060 is useful for OpenClaw's browser control (Chromium GPU rendering) and optional local model inference.

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

# Install NVIDIA driver (recommended: use Ubuntu's built-in driver manager)
sudo apt install -y nvidia-driver-550

# Reboot after driver installation
sudo reboot

After reboot, verify the driver:

# Check NVIDIA driver
nvidia-smi

# You should see your RTX 3060 with driver version and CUDA version

Optional — Install CUDA Toolkit (only needed if running local models via Ollama, llama.cpp, etc.):

# Install CUDA toolkit
sudo apt install -y nvidia-cuda-toolkit

# Verify
nvcc --version

6. Install OpenClaw

As the clawdbot user, install OpenClaw globally via npm:

Option A: Quick Install (npm global — recommended)

# As clawdbot user
npm install -g openclaw@latest

# Verify installation
openclaw --version

Option B: One-Liner Installer

# The installer handles Node.js and everything automatically
curl -fsSL https://openclaw.ai/install.sh | bash

Option C: From Source (Hackable)

cd /home/clawdbot
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install pnpm if not present
npm install -g pnpm

pnpm install
pnpm ui:build
pnpm build

# Run via pnpm
pnpm openclaw --version

7. Run the Onboarding Wizard

The onboarding wizard walks you through setting up the Gateway, workspace, AI model, and channels:

# Run onboarding and install the background daemon
openclaw onboard --install-daemon

The wizard will guide you through:

  1. Model selection — Choose Anthropic Claude (recommended: anthropic/claude-opus-4-5)
  2. Authentication — Enter your API key or OAuth credentials
  3. Gateway setup — Configures the local WebSocket server on port 18789
  4. Channel setup — Select WhatsApp and configure your phone number
  5. Workspace & identity — Name your assistant and set personality
  6. Daemon install — Creates a systemd user service for always-on operation

Important: The --install-daemon flag installs a systemd user service so the gateway auto-starts and stays running.

8. Configure OpenClaw

OpenClaw's configuration lives in ~/.openclaw/openclaw.json. The wizard creates this, but you can edit it manually:

# Open the config file
vim ~/.openclaw/openclaw.json

Minimal Configuration Example

{
  "agent": {
    "model": "anthropic/claude-opus-4-5"
  },
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+1XXXXXXXXXX"]
    }
  },
  "browser": {
    "enabled": true
  }
}

Key Configuration Paths

9. Set Up WhatsApp Channel

Step 1: Get a Phone Number

Step 2: Configure WhatsApp in openclaw.json

Dedicated Number Setup (Recommended)

{
  "channels": {
    "whatsapp": {
      "dmPolicy": "allowlist",
      "allowFrom": ["+1XXXXXXXXXX"]
    }
  }
}

Replace +1XXXXXXXXXX with your personal phone number (the one you'll message FROM).

Personal Number Setup (Self-Chat Mode)

{
  "channels": {
    "whatsapp": {
      "selfChatMode": true,
      "dmPolicy": "allowlist",
      "allowFrom": ["+1XXXXXXXXXX"]
    }
  }
}

Step 3: Link WhatsApp via QR Code

# This displays a QR code in the terminal
openclaw channels login
  1. Open WhatsApp on your phone (the phone with the dedicated number)
  2. Go to Settings → Linked Devices → Link a Device
  3. Scan the QR code shown in the terminal
  4. Wait for confirmation — credentials are saved to ~/.openclaw/credentials/whatsapp/

Step 4: Start (or Restart) the Gateway

# If using systemd daemon (installed during onboard)
systemctl --user restart openclaw-gateway

# Or start manually for testing
openclaw gateway --port 18789 --verbose

Step 5: Test It!

WhatsApp DM Policies

WhatsApp Group Support

{
  "channels": {
    "whatsapp": {
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  }
}

Use "*" to allow all groups or specify group JIDs. With requireMention: true, the bot only responds when @mentioned.

10. Run as a systemd Service (Always-On)

If you used openclaw onboard --install-daemon, a systemd user service was already created. If not, set it up manually:

# Create the systemd user directory
mkdir -p ~/.config/systemd/user/

Create the service file:

cat << 'EOF' > ~/.config/systemd/user/openclaw-gateway.service
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
Environment=NODE_ENV=production

[Install]
WantedBy=default.target
EOF

Note: If you installed Node via nvm, adjust the ExecStart path:

# Find your openclaw binary path
which openclaw
# Example: /home/clawdbot/.nvm/versions/node/v22.x.x/bin/openclaw
# Update ExecStart accordingly

Enable and start the service:

# Reload systemd
systemctl --user daemon-reload

# Enable auto-start on boot
systemctl --user enable openclaw-gateway

# Start the service now
systemctl --user start openclaw-gateway

# Check status
systemctl --user status openclaw-gateway

# View logs
journalctl --user -u openclaw-gateway -f

Important: For the service to run after logout, enable linger:

sudo loginctl enable-linger clawdbot

11. Browser Control (Optional)

OpenClaw can control a Chromium browser for web browsing, form filling, and data extraction. The RTX 3060 helps with GPU-accelerated rendering.

# Install Chromium and dependencies
sudo apt install -y chromium-browser

# Or install Google Chrome
wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt --fix-broken install -y

Enable browser in your config:

{
  "browser": {
    "enabled": true
  }
}

If running headless (no display), install Xvfb:

sudo apt install -y xvfb
# OpenClaw handles headless mode internally, but Xvfb can help with edge cases

For browser troubleshooting on Linux, see: docs.openclaw.ai/tools/browser-linux-troubleshooting

12. Verify and Troubleshoot

Run the Doctor

# Diagnoses configuration, channels, and gateway health
openclaw doctor

Check Gateway Status

# Gateway health check
openclaw health

# Detailed status
openclaw status

Check Channel Status

# See all connected channels
openclaw channels status

View Logs

# Real-time log streaming
openclaw logs --follow

# Or read the log file directly
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

Common Issues

13. Useful Commands Reference

Gateway Control

# Start gateway (foreground, verbose)
openclaw gateway --port 18789 --verbose

# Restart systemd service
systemctl --user restart openclaw-gateway

# Stop the gateway
systemctl --user stop openclaw-gateway

Chat & Messaging

# Send a message from CLI
openclaw message send --to "+1XXXXXXXXXX" --message "Hello from OpenClaw!"

# Talk to the agent directly
openclaw agent --message "What can you do?"

# Send with high thinking level
openclaw agent --message "Analyze this problem" --thinking high

Session Management

# List active sessions
openclaw sessions list

# Reset a session
openclaw sessions reset

WhatsApp Chat Commands

Send these in WhatsApp to your OpenClaw bot:

Updating OpenClaw

# Update to the latest version
npm update -g openclaw@latest

# Or use the built-in updater
openclaw update

# Run doctor after update to migrate configs
openclaw doctor

Skills & Plugins

# List installed skills
openclaw skills list

# Search for skills on ClawHub
openclaw skills search "gmail"

# Install a skill
openclaw skills install <skill-name>

Directory Structure Summary

/home/clawdbot/
├── .openclaw/
│   ├── openclaw.json          # Main configuration file
│   ├── workspace/
│   │   ├── AGENTS.md          # Agent prompt file
│   │   ├── SOUL.md            # Personality/soul file
│   │   ├── TOOLS.md           # Tools configuration
│   │   └── skills/            # Installed skills
│   └── credentials/
│       └── whatsapp/
│           └── default/
│               └── creds.json # WhatsApp session credentials
├── .config/
│   └── systemd/
│       └── user/
│           └── openclaw-gateway.service  # systemd service
└── .npm-global/               # npm global packages (if configured)

Helpful Links