OpenClaw Linux Install: Step-by-Step for Ubuntu and Debian

ByL.B. Kaelin

OpenClaw Linux Install: Step-by-Step for Ubuntu and Debian

If you run a VPS or Linux server, you probably want OpenClaw running on it. The OpenClaw desktop app works on macOS, Windows, and Linux, but the real power comes when you run it as a persistent service on a Linux machine that stays online 24/7.

This guide covers the exact steps to install OpenClaw on Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, and Debian 12 (Bookworm). These are the three most common Linux distributions for VPS hosting on DigitalOcean, Linode, Hetzner, and AWS. By the end, you will have OpenClaw running as a systemd service that starts automatically on boot and restarts if it crashes.

Prerequisites: What You Need

Before starting, make sure you have the following:

  • A server or machine running Ubuntu 22.04 LTS, Ubuntu 24.04 LTS, or Debian 12 (Bookworm)
  • Root or sudo access to the machine. You need this to install packages and create systemd services.
  • An LLM API key for the AI model you want to use with OpenClaw (OpenAI, Anthropic Claude, Google Gemini, or any OpenRouter-compatible provider). You will configure this during the setup wizard.
  • Basic familiarity with the terminal. You should know how to SSH into your server and run commands. If you are new to Linux, follow each command exactly as written.

Step 1: Install Node.js (The Right Way)

OpenClaw runs on Node.js. The version of Node.js in the default Ubuntu and Debian package repositories is too old. Do not use sudo apt install nodejs. Install the current LTS release (v22.x) from NodeSource, the official third-party repository maintained by the Node.js Foundation.

Run these commands:

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

The first command adds the NodeSource repository to your system. The second installs Node.js and npm.

Verify the installation:

node --version

You should see v22.x (the exact minor version may vary).

npm --version

This should return a version number like 10.x or later.

If you see an error about curl not being found, install it first with sudo apt install curl.

Step 2: Install OpenClaw

With Node.js installed, install OpenClaw globally using npm:

sudo npm install -g openclaw

The -g flag installs OpenClaw globally so the openclaw command is available anywhere on your system. The sudo prefix is necessary on most Linux systems because the global npm directory is owned by root.

Verify the installation:

openclaw --version

You should see a version number printed. If you get command not found, check that the npm global bin directory is in your PATH. It is usually at /usr/local/bin, which is included by default on Ubuntu and Debian.

Step 3: Firewall Configuration (VPS Only)

If you are installing OpenClaw on a VPS with a public IP address, you need to open port 3000 in your firewall to access the web UI. The standard firewall tool on Ubuntu and Debian is ufw (Uncomplicated Firewall).

Open port 3000 for TCP traffic:

sudo ufw allow 3000/tcp

If ufw is not enabled, you can enable it with:

sudo ufw enable

Check the firewall status:

sudo ufw status

You should see 3000/tcp listed with ALLOW status.

Alternative: SSH Tunnel (More Secure)

For better security, you can keep the firewall closed on port 3000 and use an SSH tunnel to access the web UI. This means only your SSH connection can reach OpenClaw, and no one else on the internet can scan or access it.

From your local machine, run:

ssh -L 3000:localhost:3000 user@your-server-ip

Then open http://localhost:3000 in your browser. Traffic is encrypted through SSH and never exposed to the public network.

Step 4: Start OpenClaw and Run the Setup Wizard

Start the OpenClaw daemon:

openclaw start

OpenClaw starts in the background. Open your browser and navigate to:

http://localhost:3000

(If you are on a remote server, use the SSH tunnel command above first, or replace localhost with your server’s IP if you opened the firewall in Step 3.)

The first time you access the web UI, OpenClaw guides you through a setup wizard. You will:

  • Choose an AI provider and enter your API key
  • Set a password for the web interface
  • Configure your workspace directory (default is ~/.openclaw/workspace/)

Complete the wizard and verify the agent is responding before moving to the next step.

Step 5: Set Up OpenClaw as a systemd Service

The openclaw start command runs the daemon in the background, but it stops when you log out of your SSH session. To keep OpenClaw running permanently, set it up as a systemd service.

Create a service file:

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

Paste the following content, replacing <your-user> with your actual Linux username:

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

[Service]
User=<your-user>
ExecStart=/usr/bin/openclaw start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Find your username with whoami if you are not sure. The After=network.target line ensures the service starts after the network is available. Restart=always with RestartSec=5 means OpenClaw restarts automatically after 5 seconds if it crashes.

Save the file and exit (Ctrl+X, then Y, then Enter in nano).

Now 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: active (running) in green. The status output also shows recent log entries. Press Q to exit the status view.

Test that OpenClaw survives a logout by closing your SSH session, logging back in, and checking the status again. It should still show active (running).

Step 6: (Optional) Nginx Reverse Proxy for HTTPS

If you want to access OpenClaw through a domain name with HTTPS, set up Nginx as a reverse proxy. This is useful for production deployments where you want encrypted connections and a clean URL.

Install Nginx:

sudo apt install nginx

Create a site configuration:

sudo nano /etc/nginx/sites-available/openclaw

Add this configuration, replacing your-domain.com with your actual domain:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Install Certbot to get a free SSL certificate from Let’s Encrypt:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Follow the prompts. Certbot automatically modifies your Nginx configuration to enable HTTPS and sets up automatic certificate renewal.

After this, you can access OpenClaw at https://your-domain.com with a valid SSL certificate.

Common Errors and Fixes

EACCES Permission Error on npm Install

If you see an EACCES: permission denied error when running npm install -g openclaw, it means your npm global directory is not writable by your user. The simplest fix is to use sudo:

sudo npm install -g openclaw

If you prefer not to use sudo, you can reconfigure npm’s global directory. See the npm documentation for instructions on configuring a prefix directory that your user owns.

Port 3000 Already in Use

If another process is already using port 3000, OpenClaw will fail to start. Find the conflicting process:

sudo lsof -i :3000

This shows the PID (process ID) of the process using port 3000. You can stop it with sudo kill <PID>, or change OpenClaw’s port in its configuration file if you need to keep the other process running.

systemd Service Not Starting

If sudo systemctl status openclaw shows Active: failed, check the logs:

journalctl -u openclaw -f

The -f flag follows new log entries in real time. Common causes of service failure include:

  • The User directive in the service file points to a user that does not exist on the system
  • The workspace directory is not writable by the service user
  • The ExecStart path is wrong. Verify the location of the openclaw binary: which openclaw
  • Network is not available when the service starts. The After=network.target line in the service file usually prevents this, but some VPS configurations may need Wants=network-online.target

OpenClaw Workspace Directory Permissions

The default workspace path is ~/.openclaw/workspace/. The systemd service runs as the user specified in the User directive, and that user must have write access to the workspace directory. If you configured a custom workspace path, verify the permissions:

ls -la /path/to/your/workspace

The directory should be owned by the user running the service. If not, correct it:

sudo chown -R your-user:your-user /path/to/your/workspace

What to Do After Install

With OpenClaw installed and running as a service, you can move on to configuring your agent. Here are the recommended next steps:

  • Write a SOUL.md file in your workspace to define your agent’s personality and behavior. This is OpenClaw’s core configuration file.
  • Set up your first cron job to give your agent recurring tasks. OpenClaw can run automated workflows on a schedule.
  • Configure plugins to connect OpenClaw to Slack, email, databases, or other services that your agent needs to interact with.

For a complete walkthrough of the setup process after installation, read the OpenClaw Setup Guide. If you are deploying on a specific cloud provider, the VPS Deployment Guide for DigitalOcean, Linode, and Hetzner covers provider-specific configuration.

Sources

This guide was verified against the following references:

  • OpenClaw official documentation and command-line help
  • NodeSource installation instructions for Linux
  • Ubuntu 22.04 LTS and 24.04 LTS server documentation
  • Debian 12 (Bookworm) release notes and package management documentation
  • Nginx documentation for reverse proxy configuration
  • Certbot documentation for Let’s Encrypt SSL certificates on Nginx
  • systemd service unit documentation

Similar Posts