How to Install OpenClaw on Ubuntu, Complete 2026 Guide

Why Ubuntu is a strong OpenClaw host

Ubuntu is one of the best places to run OpenClaw because it hits the sweet spot between boring and capable.

Officially supported by Docker: Yes — easier containerized deployments. Node 24 support: Yes — matches OpenClaw's recommended runtime. systemd user services: Yes — reliable gateway startup. VPS availability: Excellent — cheap hosts are everywhere. Local install complexity: Low — fastest route for solo users.

OpenClaw's docs recommend Node 24 and support Node 22.14+, with the CLI onboarding flow as the default setup path. The quickstart also says you can go from install to first message in about five minutes, which is realistic if your box is already updated and you have an API key ready.

If you want a broader deployment overview first, read How to Deploy OpenClaw: Complete Guide (Docker, VPS, Cloud) and OpenClaw Setup Guide for Beginners.

What you need before you start

Minimum practical checklist:

• Ubuntu 22.04 LTS or 24.04 LTS.
• A non-root user with sudo access.
• At least 2 GB RAM for a comfortable basic setup.
• An API key or auth flow for OpenAI, Anthropic, Google, or another supported provider.
• Outbound internet access.

Recommended baseline by use case

Basic cloud-model assistant: 1 vCPU, 2 GB RAM, 20 GB storage — fine for one personal agent. Multiple channels + skills: 2 vCPU, 4 GB RAM, 40 GB storage — better headroom. Docker + browser-heavy workflows: 2-4 vCPU, 4-8 GB RAM, 40+ GB storage — more stable under load. Local LLM experiments: 4+ vCPU, 8+ GB RAM, 60+ GB storage — usually better on a separate box.

For a deeper sizing breakdown, see OpenClaw System Requirements: Complete Hardware & Software Guide (2026) and How to Run OpenClaw with a Local LLM: Complete Ollama Setup Guide (2026).

Method 1, recommended: install OpenClaw directly on Ubuntu

This is the best option for most people. It is simpler than Docker, easier to debug, and matches the default docs flow.

Step 1: update Ubuntu first

After reboot, verify with uname -a and lsb_release -a. You do not want to debug an OpenClaw install on a half-updated box.

sudo apt update && sudo apt upgrade -y
sudo reboot

Step 2: install Node 24

OpenClaw requires Node 22.14 or newer, and the docs explicitly recommend Node 24.

On Ubuntu, OpenClaw's Node setup page uses NodeSource for the Linux install path. You want node -v to return v24.x.x ideally.

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

node -v
npm -v

Step 3: install OpenClaw

OpenClaw's getting-started docs recommend the installer script on macOS and Linux. If you prefer npm directly, the GitHub README also documents the npm install approach.

If Ubuntu says openclaw: command not found, skip ahead to the troubleshooting section. That is almost always a PATH issue.

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

npm install -g openclaw@latest

openclaw --version

Step 4: run onboarding

This is the part that actually wires the system together.

• model provider auth
• workspace location
• gateway port and bind mode
• channels
• daemon install
• health check
• recommended skills

openclaw onboard --install-daemon

Step 5: verify the gateway

If the dashboard opens, you're basically done. OpenClaw's default gateway port is 18789.

If you want a primer on what the gateway token is doing, read the OpenClaw Gateway Token: Complete Setup, Security & Troubleshooting Guide (2026).

openclaw gateway status
openclaw dashboard
openclaw health

Fastest real-world setup: connect Telegram after install

The Control UI is enough to prove the install works, but Telegram is the fastest way to make OpenClaw actually useful on day one.

Typical flow: create a bot with BotFather, copy the token, add the Telegram channel during onboarding or afterward, message the bot and approve pairing.

If you want the full walkthrough, use How to Connect OpenClaw to Telegram in 10 Minutes.

Recommended Ubuntu post-install hardening

A lot of people install OpenClaw correctly, then immediately weaken it by exposing the gateway publicly. Don't do that.

OpenClaw's security docs are very clear about the trust model: it is designed for a personal assistant deployment, not a hostile multi-tenant shared environment.

If you're exposing anything beyond localhost, also read OpenClaw Security Hardening Guide: Complete Production Setup (2026) and How to Run OpenClaw Behind Tailscale (Zero-Trust Setup).

• Keep gateway.bind on loopback unless remote access is genuinely required.
• Use token auth.
• Keep DM policies strict, pairing or allowlist.
• Do not give broad exec access to agents you haven't locked down.
• Run openclaw security audit after setup changes.
• Prefer Tailscale or a reverse proxy over direct public exposure.

openclaw security audit
openclaw security audit --deep
openclaw doctor

Method 2: install OpenClaw on Ubuntu with Docker

Docker is optional. OpenClaw's docs say that directly. Use it if you want a containerized gateway or cleaner isolation, not because some YouTube guy says Docker is always better.

When Docker is worth it

Use Docker if you're deploying on a VPS, you want easier rebuilds and rollback hygiene, you already manage everything with Compose, or you want cleaner separation between host and runtime.

Avoid Docker if you are new to Linux, you want the simplest possible debug path, or you are just trying to get your first agent running today.

Docker Step 1: install Docker Engine and Compose plugin

Docker's Ubuntu docs support both Ubuntu 24.04 and 22.04, and the current install flow uses Docker's apt repository.

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

sudo tee /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

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

sudo docker run hello-world
docker compose version

Docker Step 2: run OpenClaw's Docker setup flow

The Docker docs use the repo's setup script. That flow builds or pulls the image, runs onboarding, generates a gateway token, and starts the gateway with Docker Compose.

The docs also note a practical constraint that matters on cheap VPSes: 2 GB RAM is recommended for image build, because installs on 1 GB hosts may die with exit 137. That's one of the few concrete numbers in the official docs, and it's worth paying attention to.

./scripts/docker/setup.sh

Docker Step 3: verify health

If Docker is your preferred route, also read How to Run OpenClaw in Docker: The Complete Setup Guide (2026) and OpenClaw Docker Complete Guide: Containerize Your AI Agent in 2026.

curl -fsS http://127.0.0.1:18789/healthz
curl -fsS http://127.0.0.1:18789/readyz

Direct install vs Docker on Ubuntu

Initial setup speed: Direct is faster. Debugging: Direct is easier. Isolation: Docker is higher. Resource overhead: Docker is higher. Best for beginners: Direct install, yes. Best for VPS standardization: Docker, excellent.

My recommendation is simple: install directly first, use Docker second. That's the sane path unless you already live in Docker.

Common Ubuntu issues and fixes

Here are the most common problems people hit when installing OpenClaw on Ubuntu and how to fix each one.

openclaw: command not found

Cause: npm global bin directory is missing from PATH.

Then add that export line to ~/.bashrc or ~/.zshrc.

npm prefix -g
echo "$PATH"
export PATH="$(npm prefix -g)/bin:$PATH"

EACCES on npm install -g

Cause: global npm install path is not user-writable.

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

Gateway won't start after onboarding

Check status first. Usually the culprit is one of these: old Node version, broken auth config, port already in use, or bad JSON config edit.

openclaw gateway status
openclaw doctor
openclaw gateway restart

Port 18789 is unreachable

If you installed locally and bound to loopback, that is expected from outside the host. That's the secure default.

If you intentionally need remote access, do it properly with Tailscale or a hardened reverse proxy. Do not just throw the gateway onto 0.0.0.0 and pray.

Docker install works, browser cannot reach the dashboard

The Docker docs note the distinction between lan and loopback bind behavior. For host browser access with published ports, lan is the usual Docker choice.

Updates break something

Use the official updater first. If you need rollback, pin a known-good npm version or restore your source checkout to a previous commit.

For the full playbook, see How to Update OpenClaw: Complete Guide to Updates, Channels & Rollbacks (2026).

openclaw update
openclaw doctor
openclaw gateway restart

Best practice Ubuntu configuration after first install

A clean starter setup for most solo users looks like the configuration below. Then widen capabilities only when you know why you need them.

If you're planning to use OpenClaw for more advanced workflows, these guides pair well with an Ubuntu install: OpenClaw Best Practices: 21 Rules for a Faster, Cheaper, More Reliable AI Agent (2026), How to Use MCP Servers with OpenClaw: Complete Setup Guide (2026), and OpenClaw Web Search Setup: Complete Guide to Every Provider (2026).

{
  "gateway": {
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token"
    }
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "tools": {
    "profile": "messaging"
  }
}

Final verdict

If your goal is to install OpenClaw on Ubuntu with the least pain, the winning recipe is boring:

• Update Ubuntu.
• Install Node 24.
• Run the official OpenClaw installer.
• Use openclaw onboard --install-daemon.
• Keep the gateway on loopback.
• Add Telegram.
• Run openclaw security audit before you get clever.

Conclusion

That setup is fast, stable, and easy to maintain. Docker is great when you know why you want it. For everyone else, direct install on Ubuntu is the move.

Frequently asked questions