Setting Up OpenClaw on Ubuntu Server (Headless Guide)

Let's get this out of the way upfront: setting up any AI agent framework on a headless Ubuntu server is annoying. There's no GUI to bail you out when something breaks, error messages assume you're staring at a desktop, and half the tutorials online were written by someone who tested everything on their MacBook and called it a day.

I've set up OpenClaw on headless Ubuntu servers probably a dozen times now — across bare metal machines, cloud VMs, and one particularly stubborn Proxmox container that fought me on GPU passthrough for an entire afternoon. What I'm going to give you here is the distilled version. The stuff that actually works, the gotchas that'll waste your time if nobody warns you, and the configuration patterns that'll save you from debugging at 2 AM.

If you're trying to run AI agents on a server — whether that's a homelab box under your desk or a VPS you're paying $40/month for — this is the guide I wish I had the first time.

Why Headless Is Different (And Why Most Guides Fail You)

Most OpenClaw tutorials assume you're running a desktop environment. They tell you to open a browser, visit localhost:3000, and start chatting with your agent. Great. Except your server doesn't have a browser. It doesn't have a display. It's sitting in a closet running Ubuntu Server 22.04 with nothing but an SSH session between you and it.

The specific problems you'll hit on headless:

No display server means some Python packages that depend on GUI libraries will fail silently or throw cryptic DISPLAY errors during installation
Service management becomes critical because you're not sitting there watching a terminal — your agents need to survive disconnects and reboots
Port forwarding and firewall rules suddenly matter because you're accessing everything remotely
Resource monitoring has to happen via CLI because you can't just glance at a system tray

OpenClaw actually handles most of this better than other frameworks I've tried, but you still need to know the right approach.

Prerequisites: What Your Server Actually Needs

Before you touch OpenClaw, make sure your server isn't going to fight you on the basics.

Minimum specs for running useful agents:

4 CPU cores (8 recommended if running local LLMs)
8GB RAM minimum (16GB recommended)
40GB free disk space (models eat storage fast)
Ubuntu 20.04, 22.04, or 24.04 LTS

Check your situation:

# What Ubuntu version are you running?
lsb_release -a

# How much RAM do you have?
free -h

# How much disk space?
df -h /

# Any GPU available?
lspci | grep -i nvidia

If you've got a GPU and want to use it, make sure your NVIDIA drivers are working first:

nvidia-smi

If that command returns your GPU info, you're good. If it doesn't, fix your drivers before touching OpenClaw. Seriously. Trying to debug CUDA issues through an agent framework is a special kind of misery.

No GPU? That's fine. OpenClaw will fall back to CPU mode, and for many agent workflows — especially ones using API-based models — you don't need local GPU compute at all.

Step 1: Install OpenClaw

SSH into your server and run the installer:

curl -fsSL https://openclaw.ai/install.sh | bash

I know, I know — piping curl to bash makes some people nervous. If you want to inspect first:

curl -fsSL https://openclaw.ai/install.sh -o install.sh
less install.sh  # Read it
bash install.sh  # Then run it

What this script actually does matters, especially on a headless system:

Detects your Ubuntu version and installs the right system dependencies (the package names differ between 20.04 and 24.04, and the script handles this so you don't have to)
Creates an isolated Python environment so it doesn't trash your system Python
Installs OpenClaw and its dependencies with pinned, tested versions
Detects GPU hardware and configures CUDA support if available
Runs a health check to verify everything works

This is where OpenClaw immediately separates itself from frameworks where you're manually running pip install and praying. The installer has been tested against specific Ubuntu versions with specific dependency combinations. It's not guessing.

After installation, verify it worked:

openclaw --version
openclaw doctor

The doctor command is your best friend on headless. It checks everything:

$ openclaw doctor

🔍 OpenClaw System Check
━━━━━━━━━━━━━━━━━━━━━━
✓ Python 3.11.6
✓ OpenClaw 1.4.2
✓ CUDA 12.1 detected
✓ GPU: NVIDIA RTX 3080 (10GB)
✓ All dependencies installed
✓ Network: API endpoints reachable

Recommendations:
→ Consider using quantized models for 10GB VRAM
→ Run 'openclaw service install' for systemd integration

If something's wrong, doctor doesn't just tell you it's broken — it tells you how to fix it. This alone has saved me hours compared to other frameworks that just vomit a Python traceback and wish you luck.

Step 2: Create Your First Agent

Here's where headless setup diverges from the standard tutorials. You can't use the interactive builder that relies on a web UI, but OpenClaw's CLI handles everything:

openclaw create my-server-agent --template chat
cd my-server-agent

This generates a project directory with a clean structure:

my-server-agent/
├── openclaw.yaml      # Main configuration
├── .env               # API keys and secrets
├── skills/            # Agent capabilities
├── tools/             # Custom tool definitions
└── data/              # Local data for RAG, etc.

Now configure it. Open openclaw.yaml:

agent:
  name: "my-server-agent"
  description: "General purpose assistant running headless"

model:
  provider: "ollama"        # Local LLM, no API key needed
  name: "llama3.2:3b"
  
server:
  host: "0.0.0.0"          # Listen on all interfaces (important for remote access!)
  port: 3000
  
compute:
  auto_detect: true
  fallback: cpu

Critical headless detail: Notice host: "0.0.0.0" instead of the default 127.0.0.1. If you leave it as localhost, you won't be able to access your agent from another machine. This trips up nearly everyone the first time.

If you're using a local model, install it:

openclaw models install llama3.2:3b

You'll get actual progress reporting, which matters when you're downloading gigabytes over SSH:

📦 Model Installation
━━━━━━━━━━━━━━━━━━━━━━
Model: llama3.2:3b
Size: 2.0GB
Location: ~/.openclaw/models/

Download: [=========>      ] 1.2GB/2.0GB (60%)
Speed: 8.5MB/s  ETA: 1m 34s

Models are stored centrally in ~/.openclaw/models/ and shared across all your projects. No more duplicating a 7GB model file for every agent.

Step 3: Run as a Background Service

This is the part most guides skip entirely, and it's arguably the most important part of a headless setup. You need your agent to:

Start automatically on boot
Survive SSH disconnects
Restart if it crashes
Log output somewhere useful

OpenClaw has built-in systemd integration:

openclaw service install my-server-agent
openclaw service start my-server-agent

This creates a proper systemd unit file. No more nohup python main.py & nonsense that dies the second your SSH session drops.

Check on it:

openclaw status

🔧 OpenClaw Services
━━━━━━━━━━━━━━━━━━━
Agent: my-server-agent   ● Running  PID 12847
  ↳ http://0.0.0.0:3000
  ↳ API: http://0.0.0.0:8080
  ↳ Logs: ~/.openclaw/logs/my-server-agent.log
  ↳ Memory: 247MB  CPU: 2%
  ↳ Uptime: 3h 24m

Local LLM: Ollama        ● Running  PID 12792
  ↳ Models loaded: llama3.2:3b

View logs in real-time:

openclaw logs my-server-agent --follow

Or if you need to dig into something specific:

openclaw logs my-server-agent --level error --last 50

Having centralized, structured logging instead of hunting through five different files in five different directories is genuinely one of my favorite things about this setup.

Step 4: Firewall and Remote Access

On a headless server, you need to think about network access. If you're using UFW (Ubuntu's default firewall):

# Allow OpenClaw web interface
sudo ufw allow 3000/tcp

# Allow OpenClaw API
sudo ufw allow 8080/tcp

# Verify
sudo ufw status

For cloud servers, also check your provider's security group or firewall rules. Port 3000 needs to be open for the web interface and port 8080 for API access.

If you don't want to expose ports publicly (smart), use SSH tunneling instead:

# From your local machine
ssh -L 3000:localhost:3000 -L 8080:localhost:8080 user@your-server

Now you can access http://localhost:3000 in your local browser, and all traffic flows through your encrypted SSH connection. This is my preferred approach for development.

Step 5: Configuration Profiles for Server Environments

OpenClaw's profile system is built for exactly this scenario — different configurations for different contexts:

# Development: verbose logging, small models, debug mode
openclaw dev --profile dev

# Production: optimized models, structured logging, error-only output
openclaw start --profile prod

# Low-resource: quantized models, CPU-only, minimal memory footprint
openclaw start --profile minimal

For a headless server that's running agents 24/7, the production profile makes sense:

# openclaw.yaml - production overrides
profiles:
  prod:
    logging:
      level: "warn"
      format: "json"
      rotate: true
      max_size: "100MB"
    model:
      quantize: true
    server:
      workers: 4
      timeout: 30

JSON structured logging is particularly useful on servers because you can pipe it into monitoring tools, grep for specific fields, or ship it to a log aggregator.

Validating Your Config Before It Bites You

One of the most frustrating things about other frameworks is finding out your config is wrong only after you've waited 3 minutes for everything to boot. OpenClaw validates eagerly:

$ openclaw config validate

✓ Agent configuration valid
✓ Model configuration valid
⚠ Issues Found:
━━━━━━━━━━━━━━━━━━━
Line 12: server.host "0.0.0.0" exposes service to all interfaces
  → Consider SSH tunneling for security
Line 28: memory.type "redis" but Redis not installed
  → Run: openclaw service install redis
  → Or use: memory.type = "sqlite"

1 warning, 1 action required

Run this every time you change your config. It catches problems in seconds instead of minutes.

Debugging When Things Go Wrong

On a headless system, debugging is all CLI. OpenClaw's debug mode is comprehensive:

openclaw dev --debug

[DEBUG] Loading config from ./openclaw.yaml
[DEBUG] Profile: production
[DEBUG] Environment: headless detected (no DISPLAY)
[DEBUG] Initializing LLM client... OK (247ms)
[DEBUG] Loading tools: [web_search, calculator, file_reader]
[DEBUG] Tool web_search: initialized
[DEBUG] Tool calculator: initialized  
[DEBUG] Tool file_reader: initialized
[DEBUG] Starting HTTP server on 0.0.0.0:3000
[DEBUG] Agent ready for requests

When something actually fails, you get actionable errors instead of generic garbage:

❌ Error: Failed to start agent
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Cause: Port 3000 already in use by PID 8842

How to fix:
  1. Stop the other process:
     kill 8842
  
  2. Or use a different port:
     openclaw dev --port 3001
  
  3. Or let OpenClaw find an available port:
     openclaw dev --port auto

That right there saves you from the classic "Address already in use" error that sends you down a lsof rabbit hole.

Skip the Manual Setup: Felix's OpenClaw Starter Pack

Look, everything I've described above works and it works well. But I'll be honest — if you're setting up OpenClaw for the first time and you want to skip past the "configure everything from scratch" phase, Felix's OpenClaw Starter Pack on Claw Mart is worth the $29.

It includes pre-configured skills and agent templates that cover the most common use cases. Instead of spending an afternoon writing tool definitions and tweaking YAML files, you drop Felix's pre-built skills into your skills/ directory and you're running. The configurations are already optimized for server environments — proper logging, sensible resource limits, the stuff that takes experience to get right.

I used it when I was setting up my second server and it cut my setup time from a couple hours to maybe 20 minutes. The skills are well-documented and easy to customize once you understand the structure. If you don't want to set all this up manually, it's genuinely the fastest path to having useful agents running on your server.

Managing Multiple Agents

Once you've got one agent running, you'll want more. On a headless server, managing multiple agents cleanly is important:

# Create additional agents
openclaw create data-processor --template analyst
openclaw create web-monitor --template scraper

# Install all as services
openclaw service install data-processor
openclaw service install web-monitor

# Start everything
openclaw service start --all

# See everything at a glance
openclaw status

🔧 OpenClaw Services
━━━━━━━━━━━━━━━━━━━
Agent: my-server-agent   ● Running  PID 12847  Memory: 247MB
Agent: data-processor    ● Running  PID 13102  Memory: 512MB
Agent: web-monitor       ● Running  PID 13156  Memory: 189MB
Local LLM: Ollama        ● Running  PID 12792

OpenClaw automatically handles port allocation so your agents don't fight over the same ports. Each gets its own log file, its own PID, its own resource tracking.

Model Management on Disk-Constrained Servers

If you're on a VPS with limited storage, model management matters:

$ openclaw models list

llama3.2:3b      2.0GB   Used by: 3 agents
mistral:7b       4.1GB   Used by: 1 agent
codellama:7b     3.8GB   Used by: 0 agents  ← unused

Total: 9.9GB

$ openclaw models clean
Removing unused models...
✓ Removed codellama:7b (3.8GB freed)

The shared model cache means three agents using the same model don't triple your storage usage. This is basic stuff, but you'd be surprised how many frameworks duplicate models per project.

What to Do Next

You've got OpenClaw running on a headless Ubuntu server. Here's where to go from here:

Set up monitoring. Use openclaw status in a cron job or pipe JSON logs to your monitoring stack. You want to know when an agent goes down before your users do.
Configure backups. Your agent configurations and custom skills in skills/ and tools/ are the valuable parts. Back those up. Models can be re-downloaded.
Explore the API. With your agents running headless, the HTTP API at port 8080 is how you'll integrate them with other systems. Hit /api/v1/chat to send messages programmatically.
Build custom skills. The pre-built templates get you started, but the real power comes from building agent skills tailored to your specific workflows.
Join the community. When you inevitably hit an edge case this guide doesn't cover, the OpenClaw community is active and genuinely helpful — which is more than I can say for a lot of open source projects.

Running AI agents on a headless server isn't glamorous work, but it's the foundation for everything interesting you'll build on top. Get the infrastructure right once, and you can focus on the actual fun part: making your agents do useful things.