How to Install OpenClaw on Ubuntu (Step-by-Step 2026 Guide)

OpenClaw is a powerful self-hosted chatbot framework that lets you run AI assistants on Telegram and WhatsApp. This guide walks you through a complete installation on Ubuntu 22.04 LTS and Ubuntu 24.04 LTS from scratch.

Estimated time: 30–45 minutes Requirements: Ubuntu 22.04 or 24.04 server, at least 2 GB RAM (4 GB recommended), 10 GB free disk space

Step 1: Update Your System

Before installing anything, update your package lists and upgrade existing packages.

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl wget git ca-certificates gnupg lsb-release

Reboot if a kernel update was applied:

sudo reboot

Step 2: Install Docker on Ubuntu

OpenClaw is distributed as a Docker image, so Docker is required.

Remove old Docker versions

sudo apt remove -y docker docker-engine docker.io containerd runc

Add Docker's official APT repository

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg |   sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo   "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg]   https://download.docker.com/linux/ubuntu   $(. /etc/os-release && echo "$VERSION_CODENAME") stable" |   sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Install Docker Engine

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify Docker is running

sudo systemctl enable docker
sudo systemctl start docker
docker --version

Add your user to the docker group (avoid sudo for every command)

sudo usermod -aG docker $USER
newgrp docker

Tip: Log out and back in if newgrp doesn't persist.

Step 3: Install Node.js 20+ (Optional but Recommended)

While OpenClaw runs inside Docker, having Node.js on the host is useful for scripting and config generation.

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node --version   # Should print v20.x.x or higher
npm --version

Step 4: Pull the OpenClaw Docker Image

docker pull alpine/openclaw:latest

This downloads the official OpenClaw image (~300 MB). The image runs on Alpine Linux with Node.js included.

Warning: OpenClaw requires at least 2048 MB of RAM. The gateway compiles a WASM sandbox on first start which peaks at ~1.3 GB. With less RAM the container will be OOM-killed.

Step 5: Create the Configuration Directory

mkdir -p /opt/openclaw/config

Create the OpenClaw configuration file:

cat > /opt/openclaw/config/openclaw.json << 'EOF'
{
  "gateway": {
    "mode": "local",
    "controlUi": {
      "dangerouslyDisableDeviceAuth": true
    }
  },
  "agents": {
    "default": {
      "model": "claude-3-5-sonnet-20241022"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
      "dmPolicy": "open"
    }
  }
}
EOF

Replace YOUR_TELEGRAM_BOT_TOKEN with your actual bot token from @BotFather.

Step 6: Run OpenClaw

docker run -d   --name openclaw   --restart unless-stopped   -p 8080:8080   -v /opt/openclaw/config:/home/node/.openclaw   -e ANTHROPIC_API_KEY=your_api_key_here   -e NODE_OPTIONS=--max-old-space-size=1536   -m 2048m   alpine/openclaw:latest   node /app/openclaw.mjs gateway

Check container logs to watch startup progress:

docker logs -f openclaw

Note: The gateway takes approximately 5 minutes to start on first launch. It compiles a WebAssembly sandbox during this time. You will see high CPU usage — this is normal.

Wait until you see a line like:

Gateway listening on 127.0.0.1:18789

Step 7: Set Up a TCP Proxy (Expose the Web UI)

OpenClaw binds its web interface to localhost only. To access it from outside the server, run a simple proxy:

docker exec openclaw node -e "
const net = require('net');
net.createServer(c => {
  const r = net.connect(18789, '127.0.0.1');
  c.pipe(r); r.pipe(c);
}).listen(8080, '0.0.0.0');
console.log('Proxy: 0.0.0.0:8080 -> 127.0.0.1:18789');
"

Now you can access the OpenClaw Control UI at http://YOUR_SERVER_IP:8080.

Step 8: Set Up systemd for Auto-Restart

Create a systemd service so OpenClaw restarts automatically on boot:

sudo tee /etc/systemd/system/openclaw.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=docker.service
Requires=docker.service

[Service]
Restart=always
ExecStart=/usr/bin/docker start -a openclaw
ExecStop=/usr/bin/docker stop openclaw

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw

Check service status:

sudo systemctl status openclaw

Step 9: Configure UFW Firewall

Allow only the necessary ports:

sudo ufw allow ssh
sudo ufw allow 8080/tcp    # OpenClaw web UI
sudo ufw --force enable
sudo ufw status

Tip: If you set up Nginx as a reverse proxy later, allow port 80 and 443 instead of 8080.

Step 10: Connect Your Telegram Bot

1. Open Telegram and talk to @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token (format: 123456789:AABBcc...)
4. Update your config file:

sudo nano /opt/openclaw/config/openclaw.json

Set the botToken field to your token, then restart:

docker restart openclaw

Your bot should now respond to messages in Telegram.

Step 11: Connect WhatsApp (Optional)

WhatsApp integration uses the official WhatsApp Business API pairing flow. Add to your config:

"whatsapp": {
  "enabled": true,
  "dmPolicy": "open",
  "selfChatMode": true,
  "accounts": {
    "default": {
      "dmPolicy": "open"
    }
  }
}

Important: Set dmPolicy at both the channel level and the account level. If only set at one level, the gateway may auto-override it.

After updating the config, restart the gateway and open the Control UI to scan the WhatsApp QR code.

Troubleshooting Common Ubuntu Issues

Container exits immediately: Check logs with docker logs openclaw. Usually caused by a config syntax error or unrecognized key. Validate JSON with cat /opt/openclaw/config/openclaw.json | python3 -m json.tool.

OOM killed (Exit 137): Your server has less than 2 GB RAM available. Use free -h to check. Stop other services or upgrade your server.

Port 8080 already in use:

sudo ss -tlnp | grep 8080

Kill the conflicting process or use a different port.

Docker permission denied: Run sudo usermod -aG docker $USER and re-login.

WASM compilation takes too long: This is normal. The 5-minute init only happens on the first start after a fresh install.

Next Steps

Once OpenClaw is running on Ubuntu, consider:

• Setting up Nginx reverse proxy with Let's Encrypt SSL for HTTPS access
• Configuring log rotation to prevent disk fill-up
• Using ClawMates for a managed experience — no server maintenance required

Managing your own server works well but requires ongoing maintenance. ClawMates handles everything automatically with a one-click deploy and $29.99/month all-inclusive pricing.