Set Up OpenClaw on Ubuntu Linux VPS

Look, I'll save you the three hours of Googling I burned through the first time I tried to get an AI agent framework running on a VPS. Setting up OpenClaw on Ubuntu should be straightforward. In practice, it's a minefield of dependency conflicts, display server nonsense, and cryptic errors that make you question your career choices — unless you know exactly what to do going in.

This post is the guide I wish I'd had. We're going from a fresh Ubuntu VPS to a fully operational OpenClaw instance, step by step, with every gotcha flagged in advance so you don't have to debug them at 2 AM.

Why This Is Harder Than It Should Be (And Why OpenClaw Fixes It)

If you've ever tried to spin up an AI agent framework on a Linux server, you already know the pain. You clone a repo, run pip install, and immediately get hit with Python version conflicts. Your system ships Python 3.10 but the framework demands 3.11. You install 3.11 alongside it, and now your system package manager is confused. You try a virtual environment, but some dependency needs a system-level library that isn't installed. You sudo apt install that library, which upgrades something else, which breaks a different dependency.

This is the "dependency hell" that sends people back to running everything on their local Mac, which defeats the entire purpose of having a VPS.

OpenClaw sidesteps most of this by design. It uses containerized environments with locked dependency versions, handles display server configuration automatically, and manages API keys centrally instead of scattering them across a dozen .env files. The result is that setting up an AI agent platform on Ubuntu goes from a multi-hour ordeal to something you can knock out during a coffee break.

Let's get into it.

Prerequisites: What You Need Before You Start

Here's your checklist before touching the terminal:

Server Requirements:

• Ubuntu 20.04 LTS, 22.04 LTS, or 24.04 LTS (all tested and supported)
• Minimum 2 GB RAM (4 GB recommended if you're running agents that need a desktop environment)
• At least 20 GB free disk space (Docker images add up fast)
• Root or sudo access

You'll Also Need:

• An API key from your preferred AI provider (Anthropic, OpenAI, or a local model via Ollama)
• SSH access to your VPS
• About 15–20 minutes of uninterrupted time

One thing to check first — if you're on a cheap VPS, make sure your provider allows Docker. Some budget hosts (especially OpenVZ-based ones) don't support the kernel features Docker needs. KVM-based VPS providers like DigitalOcean, Linode, Vultr, and Hetzner all work fine.

Step 1: Update Your System and Handle Ubuntu Quirks

SSH into your server and start with a clean slate:

sudo apt update && sudo apt upgrade -y

Now here's the first Ubuntu-specific gotcha. If your VPS came with Snap-based Docker pre-installed, you need to get rid of it. Snap Docker and apt Docker conflict in subtle, maddening ways that will waste hours of your life:

# Check if snap Docker exists
if snap list docker &>/dev/null 2>&1; then
    echo "Snap Docker detected — removing it"
    sudo snap remove docker
fi

Also, if you're on Ubuntu 24.04, be aware that Wayland is the default display server now. OpenClaw handles this automatically, but it's good to know what you're working with:

echo $XDG_SESSION_TYPE
# Will show "wayland", "x11", or nothing (headless)

On a headless VPS (which is most likely your situation), this variable won't be set at all. That's fine — OpenClaw will spin up its own virtual display.

Step 2: Install Docker Properly

OpenClaw relies heavily on Docker for isolation. Here's the clean installation path:

# Install prerequisites
sudo apt install -y ca-certificates curl gnupg lsb-release

# Add Docker's official GPG key
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

# Add the repository
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

# Add your user to the docker group (so you don't need sudo every time)
sudo usermod -aG docker $USER

Important: Log out and back in after that last command, or the group change won't take effect. You can verify it worked:

docker run hello-world

If you see the "Hello from Docker!" message, you're good.

Step 3: Install OpenClaw

Here's where things get satisfyingly simple compared to the traditional framework setup:

curl -fsSL https://raw.githubusercontent.com/mrmeman555/openclaw/main/install.sh | bash

This single command handles everything:

• Detects your Ubuntu version and applies version-specific configurations
• Installs Python dependencies in an isolated environment (no system pollution)
• Pulls the necessary Docker images
• Sets up the OpenClaw CLI tool
• Configures virtual display support for headless servers

After installation, verify everything is in place:

openclaw --version
openclaw doctor

The doctor command is your best friend. It checks for common issues — missing dependencies, Docker permissions, display server status, disk space — and tells you exactly what to fix if something's off.

Step 4: Configure Your API Keys

This is where most frameworks make you hunt through documentation trying to figure out whether you need a .env file, an environment variable, or some config directory buried in your home folder. OpenClaw centralizes all of this:

openclaw config

You'll get an interactive wizard:

> Where is your Anthropic API key?
  1. Enter it now (stored in ~/.openclaw/secrets)
  2. Use existing environment variable
  3. Point to existing .env file

> Selected: 1
> API Key: sk-ant-***
✓ Encrypted and saved
✓ Will be automatically mounted to container
✓ Already exported to current shell

If you're using multiple providers (say, Anthropic for complex tasks and a local Ollama instance for cheaper ones), you can configure all of them:

openclaw config --provider anthropic
openclaw config --provider openai
openclaw config --provider ollama --endpoint http://localhost:11434

Keys are stored encrypted in ~/.openclaw/secrets and automatically injected into any container that needs them. No more debugging 401 errors because your key is in the wrong .env file.

Step 5: Set Up the Virtual Display (For Desktop Agents)

If your agents need to interact with a desktop environment — clicking buttons, filling forms, taking screenshots — you need a virtual display on your headless VPS. OpenClaw handles this, but here's how to set it up explicitly:

# Install virtual display dependencies
sudo apt install -y xvfb x11vnc xdotool

# OpenClaw auto-configures these, but you can manually verify:
openclaw display setup

This creates a virtual X11 display that agents can interact with. If you want to watch what your agent is doing in real-time (highly recommended during development), OpenClaw includes a web-based VNC viewer:

openclaw run --with-ui your_task.yml
# Opens a web interface at http://your-server-ip:6080

You'll see a live view of the agent's desktop, complete with a red dot showing where it's clicking, an action timeline, and pause/resume controls. This alone saves massive debugging time because you can actually see when an agent gets confused instead of parsing through megabytes of JSON logs after the fact.

Step 6: Set Safety Limits (Do This Before Running Anything)

I cannot stress this enough: configure your spending limits before you run your first agent. I've seen people on Reddit burn through $50 of API credits in ten minutes because an agent got stuck in a loop. OpenClaw has built-in guardrails, but you need to turn them on:

Create or edit ~/.openclaw/limits.yml:

max_cost_per_task: 5.00      # Maximum USD per task
max_duration: 300             # Maximum seconds per task
max_tokens_per_request: 4000  # Per-request token cap
max_actions_per_task: 50      # Max clicks/keystrokes

action_on_limit:
  cost: pause_and_notify      # Options: 'pause_and_notify' or 'abort'
  duration: abort
  tokens: compress_history    # Auto-summarize older context

You can also set limits per-run:

openclaw run --budget 2.00 --max-time 120 my_task.yml

The compress_history option for token limits is particularly clever — instead of just crashing when the context window fills up, OpenClaw automatically summarizes older messages to free up space. This prevents the "agent forgot what it was doing" problem that plagues long-running tasks.

Step 7: Run Your First Agent

Let's actually do something. OpenClaw ships with a template library that gives you production-ready starting points instead of toy "hello world" examples:

openclaw templates list

You'll see options like web_research, form_filler, data_extractor, website_monitor, and more. Let's try a simple one:

openclaw templates use web_research
cd web_research/

This creates a project directory with a pre-configured task.yml, example prompts, output formatting configs, and error handling patterns. Edit the task file to specify what you want:

# task.yml
task: web_research
query: "Latest pricing changes for major cloud VPS providers"
output_format: markdown
max_sources: 5
save_to: ./results/

Then run it:

openclaw run task.yml

That's it. The agent spins up inside a container, does its work, and saves structured output to your results directory. If you added the --with-ui flag, you can watch it work in real-time through your browser.

The Shortcut: Felix's OpenClaw Starter Pack

Now, everything above works and I've walked plenty of people through it. But if you don't want to set all of this up manually — the templates, the configurations, the display tuning, the safety limits — there's a faster option.

Felix's OpenClaw Starter Pack on Claw Mart is a $29 bundle that includes pre-configured skills and templates that are already battle-tested. Think of it as someone who's already done the trial-and-error work on prompt engineering, error handling, and output formatting handing you the finished result. You drop it into your OpenClaw installation and start running production-quality tasks immediately instead of spending days tweaking YAML files and debugging edge cases. If your time is worth anything, it pays for itself before lunch on day one.

Troubleshooting Common Issues

Even with OpenClaw smoothing out the rough edges, here are issues you might still hit:

"Permission denied" on Docker commands: You forgot to log out and back in after adding yourself to the docker group. Just do it. Or run newgrp docker as a temporary fix.

Agent screenshots are black: Your virtual display isn't running. Run openclaw display setup and then openclaw doctor to verify.

"Connection refused" on port 6080: Your VPS firewall is blocking the web UI port. Fix it:

sudo ufw allow 6080/tcp

Slow agent performance: Check your VPS resources with htop. If you're maxing out RAM, either upgrade your VPS or reduce the max_tokens_per_request in your limits config to lower memory overhead.

Firefox snap issues on Ubuntu 24.04: Ubuntu's snap-confined Firefox can't access files where agents save them. OpenClaw uses its own browser inside the container, so this shouldn't affect you. But if you need the system Firefox for something, install the deb version instead:

sudo snap remove firefox
sudo add-apt-repository ppa:mozillateam/ppa
sudo apt install -t 'o=LP-PPA-mozillateam' firefox

What to Build Next

You've got OpenClaw running on your VPS. Now what?

Start with automation tasks you're already doing manually. Seriously. Don't try to build something ambitious on day one. Pick a repetitive task — checking a website daily, compiling a report from multiple sources, filling out a form you deal with weekly — and automate that first. You'll learn how OpenClaw's task configuration works with low stakes.

Then explore the multi-provider comparison feature:

openclaw compare --providers anthropic,openai task.yml

This runs the same task on different AI models and gives you a side-by-side comparison of results, cost, and speed. It's the fastest way to figure out which provider gives you the best bang for your buck on specific task types.

The key advantage of running all of this on a VPS instead of your laptop is persistence. Set up openclaw schedule to run tasks on a cron schedule, and your agents work while you sleep. That's the whole point of having a server — let it serve.

You went from a bare Ubuntu VPS to a running OpenClaw installation in under 20 minutes. Not bad. Now go build something useful with it.