How to Install OpenClaw on Ubuntu/Debian

Introduction — Supported Operating Systems

OpenClaw is the open-source AI agent framework that lets you run a fully self-hosted personal AI assistant. It supports multiple messaging channels including Telegram, Discord, WhatsApp, and Slack, all from a single installation on your own server. Ubuntu and Debian are the most popular choices for hosting OpenClaw, and for good reason: they offer long-term support, excellent package management, and a massive community of users who can help if you run into trouble.

This guide covers installation on three specific distributions that are officially supported and thoroughly tested by the OpenClaw community:

• Ubuntu 22.04 LTS (Jammy Jellyfish) — The current long-term support release, supported until April 2027. This is the most widely deployed version on cloud servers and the safest choice for production deployments.
• Ubuntu 24.04 LTS (Noble Numbat) — The newest LTS release with updated packages and kernel improvements. Recommended for new installations where you want the latest security patches and performance optimizations.
• Debian 12 (Bookworm) — The stable Debian release known for its rock-solid reliability. Ideal if you prefer a minimal system with fewer pre-installed packages and longer release cycles.

While OpenClaw may work on other Debian-based distributions like Linux Mint or Pop!_OS, this guide focuses exclusively on the three distributions listed above. If you are using a different operating system, check the EasySetup guide which handles cross-platform installation automatically.

Prerequisites — What You Need Before Starting

Before installing OpenClaw, make sure your server meets the minimum requirements. The following table breaks down what you need for each supported operating system. Note that the requirements are nearly identical across all three distributions, with only minor differences in default package availability.

You will also need an API key from your preferred LLM provider. OpenClaw supports OpenAI, Anthropic, Google Gemini, and several other providers. Have your API key ready before starting the installation. If you are unsure which provider to choose, check our OpenClaw Cost Guide for a detailed price comparison.

For hosting, you need a VPS or dedicated server. The most affordable options start at around $4-6 per month. See our Best VPS for OpenClaw ranking for recommended providers that have been tested with OpenClaw installations.

Step 1 — Update System Packages

Always start by updating your system packages. This ensures you have the latest security patches and that your package manager index is current. Stale package lists can cause dependency resolution failures during installation.

sudo apt update && sudo apt upgrade -y

On a fresh server, this may take a few minutes depending on how many packages need updating. If prompted about kernel updates or GRUB configuration, accept the defaults. After the upgrade completes, it is a good practice to reboot if a kernel update was applied:

sudo reboot

After reconnecting to your server via SSH, verify your system is up to date:

lsb_release -a

Debian 12 — Install Additional Prerequisites

Debian 12 minimal installations may not include curl and git by default. Install them now:

sudo apt install -y curl git wget gnupg2

Step 2 — Install Node.js v22+

OpenClaw requires Node.js version 22 or later. The default Node.js packages in Ubuntu and Debian repositories are typically outdated, so you need to use the NodeSource repository to get a current version. This is the officially recommended method by both the Node.js project and the OpenClaw team.

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

After installation, verify the Node.js version:

node --version
# Expected output: v22.x.x or higher

npm --version
# Expected output: 10.x.x or higher

Step 3 — Install OpenClaw

With Node.js installed, you can now install OpenClaw using the npx command. This downloads the latest version and runs the interactive setup wizard that guides you through the initial configuration.

npx openclaw

The setup wizard will prompt you for several pieces of information:

1. Installation directory — Where to store OpenClaw files (default: ~/openclaw)
2. LLM provider — Choose between OpenAI, Anthropic, Google, or others
3. API key — Your LLM provider API key
4. Agent name — The display name for your AI agent
5. Messaging channel — Which platform to connect (Telegram, Discord, etc.)

The installation typically takes 2-3 minutes depending on your internet connection speed. OpenClaw downloads approximately 150 MB of dependencies during the first install.

Step 4 — Configure SOUL.md

SOUL.md is the heart of your OpenClaw agent. This Markdown file defines your agent's personality, knowledge base, communication style, and behavioral rules. After installation, you will find it in your OpenClaw directory.

cd ~/openclaw
nano SOUL.md

A basic SOUL.md configuration looks like this:

# Agent Identity
You are Luna, a helpful AI assistant.

## Personality
- Friendly and professional
- Concise but thorough
- Uses plain language, avoids jargon

## Knowledge
- Expert in customer support
- Familiar with our product catalog
- Can process returns and exchanges

## Rules
- Never share internal pricing
- Always escalate billing disputes to a human
- Respond in the language the user writes in

The SOUL.md file supports full Markdown syntax and can be as simple or as detailed as you need. Many users start with a basic configuration and refine it over time as they observe how their agent responds. For more advanced configurations, see the official OpenClaw documentation on personality tuning.

Step 5 — Set Up Messaging Channel

OpenClaw supports multiple messaging platforms. The most common setup is Telegram because it offers a free, easy-to-create bot API. Here is how to connect Telegram:

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to create a bot
3. Copy the bot token provided by BotFather
4. Add the token to your OpenClaw configuration:

cd ~/openclaw
nano .env

# Add this line:
TELEGRAM_BOT_TOKEN=your_bot_token_here

For Discord, you need to create a bot application at the Discord Developer Portal, enable the Message Content intent, and add the bot token to your .env file as DISCORD_BOT_TOKEN. WhatsApp integration requires a WhatsApp Business API account or a third-party bridge service.

Step 6 — Enable Auto-Start with systemd

To ensure OpenClaw starts automatically when your server boots (and restarts if it crashes), create a systemd service file. This is essential for production deployments where uptime matters.

sudo nano /etc/systemd/system/openclaw.service

Paste the following configuration, replacing your_username with your actual Linux username:

[Unit]
Description=OpenClaw AI Agent
After=network.target

[Service]
Type=simple
User=your_username
WorkingDirectory=/home/your_username/openclaw
ExecStart=/usr/bin/node /home/your_username/openclaw/index.js
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start the service:

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

Check that the service is running:

sudo systemctl status openclaw

You should see active (running) in the output. If the service fails to start, check the logs with journalctl -u openclaw -f for detailed error messages.

Step 7 — Verify Installation

The final step is to verify that everything is working. Send a test message to your bot on the messaging platform you configured. You should receive a response within a few seconds. If you connected Telegram, open the bot in your Telegram app and send "Hello" to confirm the agent responds.

You can also verify the process is running and check resource usage:

# Check if the process is running
ps aux | grep openclaw

# View real-time logs
journalctl -u openclaw -f

# Check memory and CPU usage
htop

Troubleshooting — Common Installation Issues

Even with careful setup, you may encounter issues during installation. The table below covers the most common errors reported by users installing OpenClaw on Ubuntu and Debian, along with their causes and solutions.

If your issue is not listed above, check the OpenClaw GitHub issues page or join the community Discord for help. When reporting issues, always include your Node.js version, operating system version, and the complete error message from the logs.

Performance Tuning

Out of the box, OpenClaw runs well on modest hardware. However, a few optimizations can significantly improve reliability and response times, especially on servers with limited RAM. These tuning steps are particularly important if you are running OpenClaw on a $4-6 per month VPS with only 1 GB of RAM.

Swap File Configuration

A swap file acts as overflow memory, preventing the Linux OOM killer from terminating OpenClaw when RAM is fully utilized. Even on servers with 2 GB of RAM, a swap file provides an important safety net during traffic spikes.

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

Verify the swap is active:

free -h
# You should see 2.0G under Swap

Process Manager — PM2

While systemd works well for basic setups, PM2 offers advanced features like cluster mode, log management, and automatic restart on memory limits. If you plan to run OpenClaw alongside other Node.js applications, PM2 is the better choice.

sudo npm install -g pm2
cd ~/openclaw
pm2 start index.js --name openclaw --max-memory-restart 300M
pm2 save
pm2 startup

The --max-memory-restart 300M flag automatically restarts the process if it exceeds 300 MB of memory, preventing gradual memory leaks from causing problems. PM2 also provides a built-in monitoring dashboard you can access with pm2 monit.

Memory Optimization

Reduce OpenClaw's memory footprint by adjusting the Node.js heap size and garbage collection settings:

# Add to your systemd service or PM2 config:
NODE_OPTIONS="--max-old-space-size=256 --optimize-for-size"

You can also limit the conversation history buffer in your OpenClaw configuration to prevent memory from growing unbounded over time. Keeping the last 50 messages per conversation is usually sufficient for context continuity.

Log Rotation

Without log rotation, OpenClaw's output logs can consume significant disk space over weeks and months. Configure logrotate to manage log files automatically:

sudo nano /etc/logrotate.d/openclaw

Add the following configuration:

/home/your_username/openclaw/logs/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    create 0640 your_username your_username
}

If you are using PM2, it has built-in log rotation that you can enable with pm2 install pm2-logrotate.

Security Hardening

Running any internet-connected service requires attention to security. OpenClaw itself communicates outbound to messaging APIs and LLM providers, but your server is still exposed to the internet. Follow these steps to reduce your attack surface.

Firewall Configuration with UFW

UFW (Uncomplicated Firewall) is the simplest way to manage firewall rules on Ubuntu and Debian. Configure it to allow only SSH and block everything else inbound:

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw enable

OpenClaw does not need any inbound ports open because it initiates outbound connections to messaging APIs. The only inbound port you need is SSH (port 22) for server management.

SSH Key Authentication

Disable password authentication and use SSH keys exclusively. This eliminates the most common attack vector against Linux servers:

sudo nano /etc/ssh/sshd_config

# Change these settings:
PasswordAuthentication no
PubkeyAuthentication yes
PermitRootLogin no

# Restart SSH:
sudo systemctl restart sshd

Automatic Security Updates

Enable unattended upgrades to automatically install critical security patches. This is especially important for servers that run continuously without regular manual maintenance:

sudo apt install -y unattended-upgrades
sudo dpkg-reconfigure -plow unattended-upgrades

Select "Yes" when prompted. This configures your server to automatically download and install security updates daily without requiring manual intervention. Kernel updates that require a reboot will be downloaded but not applied until you manually reboot.

Frequently Asked Questions

What version of Ubuntu does OpenClaw support?

OpenClaw officially supports Ubuntu 22.04 LTS and Ubuntu 24.04 LTS, along with Debian 12. These are the distributions that the development team tests against regularly. Older versions like Ubuntu 20.04 may work if you manually install Node.js v22+, but they are not officially supported and you may encounter compatibility issues with older system libraries.

How much RAM does OpenClaw need on Ubuntu?

The minimum requirement is 1 GB of RAM, but 2 GB is strongly recommended for stable performance. With a 2 GB swap file configured, a 1 GB server can run OpenClaw reliably under normal load. If you expect heavy usage with many concurrent conversations, consider a VPS with 4 GB of RAM. See our Best VPS for OpenClaw guide for affordable hosting options.

Can I install OpenClaw without root access?

OpenClaw itself runs as a regular (non-root) user and does not require root privileges for its core functionality. However, you need sudo access during the installation process to install Node.js from NodeSource, configure the UFW firewall, create the systemd service file, and set up log rotation. On a managed hosting platform where you have Node.js v22+ pre-installed, you could potentially run OpenClaw without any root access at all.

Does OpenClaw work on ARM-based Ubuntu servers?

Yes, OpenClaw is fully compatible with ARM64 (aarch64) architecture. This includes Oracle Cloud free-tier ARM instances (which offer up to 4 ARM cores and 24 GB RAM for free), AWS Graviton instances, and even Raspberry Pi 4 or 5 running Ubuntu Server. Node.js provides native ARM64 builds, so performance is excellent on ARM hardware.

How do I update OpenClaw on Ubuntu?

Updating is straightforward. Navigate to your OpenClaw directory and run the update command. Your SOUL.md configuration, conversation history, and environment variables are preserved during updates:

cd ~/openclaw
npx openclaw@latest

After updating, restart the service with sudo systemctl restart openclaw or pm2 restart openclaw depending on your process manager. Always check the release notes before updating in case there are breaking changes that require configuration adjustments.

Can I run multiple OpenClaw instances on one server?

Yes, you can run multiple instances on the same server, each with its own SOUL.md and messaging channel configuration. Create separate directories for each instance and use different systemd service names or PM2 process names. Each instance needs approximately 200-300 MB of RAM, so plan your server capacity accordingly.

What should I do if OpenClaw crashes repeatedly?

First, check the logs using journalctl -u openclaw --since "1 hour ago" to identify the error. The most common causes of crashes are insufficient memory (add a swap file), invalid API keys (check your .env file), and network connectivity issues. If the process is being killed by the OOM killer, you will see SIGKILL in the logs — upgrade your server RAM or optimize memory usage as described in the Performance Tuning section above.

Next Steps

Now that OpenClaw is installed and running on your Ubuntu or Debian server, here are some resources to help you get the most out of your AI agent:

• OpenClaw EasySetup — Automate future installations and updates with a single command
• Best VPS for OpenClaw — Find affordable hosting optimized for AI agent workloads
• OpenClaw Cost Guide — Understand and optimize your monthly running costs including API fees
• OpenClaw vs AutoGPT vs CrewAI — See how OpenClaw compares to other AI agent frameworks