Install OpenClaw on Ubuntu — Complete Linux Setup Guide 2026

Prerequisites

Before you begin, make sure your system meets the following requirements:

• Ubuntu 22.04 LTS or later (20.04 works but 22.04+ is recommended)
• Node.js 24.16+ or 26.1+ (Node 24 LTS is preferred; Node 22 and 25 are not supported)
• Docker Engine 24+ (for the Docker method)
• At least 512 MB of free RAM and 1 GB of disk space
• A user account with sudo privileges

Check your Ubuntu version with lsb_release -a and your Node.js version withnode --version.

Choose Your Installation Method

Method 1: Install via npm

The fastest way to get OpenClaw running on Ubuntu is via npm. You'll need Node.js 24 (24.16 or newer) installed first. The official installer, curl -fsSL https://openclaw.ai/install.sh | bash, does all of this for you, including Node.

1. Install Node.js 24 LTS using NodeSource:

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

2. Install OpenClaw globally:

   sudo npm install -g openclaw

3. Run onboarding, which sets up your AI model and chat channels and installs the gateway as a background service:

   openclaw onboard --install-daemon

4. Check it with openclaw gateway status, then open http://localhost:18789 in your browser for the web dashboard.

Method 2: Install via Docker

Docker is the recommended method for production Ubuntu servers. It keeps OpenClaw isolated and makes upgrades easy.

1. Install Docker Engine:

   sudo apt-get update
   sudo apt-get install -y 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
   echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list
   sudo apt-get update
   sudo apt-get install -y docker-ce docker-ce-cli containerd.io

2. Add your user to the docker group (so you can run docker without sudo):

   sudo usermod -aG docker $USER
   newgrp docker

3. Run OpenClaw's Docker setup script, pinned to a release so updates never arrive unannounced:

   git clone https://github.com/openclaw/openclaw.git
   cd openclaw
   OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:2026.9.8 ./scripts/docker/setup.sh

   The script runs onboarding, writes a gateway token to .env, and starts the gateway with Docker Compose.
4. Verify it is running with docker compose ps, then open http://127.0.0.1:18789/ and paste the token from .env.

See our Docker Compose guide for updates and day-to-day commands.

Method 3: Manual Build from Source

Use this method if you need to customise OpenClaw or install it in an air-gapped environment.

1. Install build dependencies:

   sudo apt-get install -y git build-essential python3

2. Clone the repository:

   git clone https://github.com/openclaw/openclaw.git
   cd openclaw

3. Install dependencies and build (the repository uses pnpm):

   npm install -g pnpm
   pnpm install
   pnpm build

4. Run OpenClaw:

   pnpm openclaw onboard --install-daemon

   From a source checkout, run every openclaw command in this guide as pnpm openclaw ... from the repository folder.

Ubuntu-Specific Tips

Run OpenClaw as a systemd Service

Let OpenClaw write the service for you rather than hand-writing a unit file. If you skipped --install-daemon during onboarding, run:

openclaw gateway install
systemctl --user status openclaw-gateway.service --no-pager

This creates a systemd user service that starts automatically and restarts on failure. On a server you log out of, also run sudo loginctl enable-linger "$USER" so the service keeps running without an open session.

Configure the Firewall with ufw

If you plan to access the OpenClaw gateway from outside the server, open port 18789 in Ubuntu's firewall:

sudo ufw allow 18789/tcp
sudo ufw status

If you're using a reverse proxy (nginx or Caddy) to serve OpenClaw on port 80/443, expose those ports instead and keep 18789 closed externally:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

Fix Permission Errors

The OpenClaw Docker container runs as user node (uid 1000). If you see "permission denied" errors when reading config files, set the correct ownership:

sudo chown -R 1000:1000 ~/openclaw

For the npm install method, if sudo npm install -g causes permission warnings, configure npm to use a user-level global directory instead:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw

Connect to Telegram or Discord

After OpenClaw is running, open http://localhost:18789 (or your server's IP on port 18789) to configure your chat channels.

Telegram

1. Create a bot via @BotFather on Telegram and copy the bot token.
2. In the OpenClaw web gateway, go to Channels → Telegram.
3. Paste your bot token and set DM Policy to pairing.
4. Save and restart the gateway. Your bot is now live on Telegram.

See the full Telegram guide for advanced configuration.

Discord

1. Create a Discord application and bot at discord.com/developers.
2. Copy the bot token and invite the bot to your server.
3. In the OpenClaw web gateway, go to Channels → Discord.
4. Paste your bot token and set DM Policy to open.
5. Save. Your Discord bot is ready to receive messages.

See the full Discord guide for more detail.

Troubleshooting Common Ubuntu Issues

Port 18789 Already in Use

Check which process is using the port:

sudo ss -tlnp | grep 18789

Kill the conflicting process or change the port in your OpenClaw config and Docker run command (e.g., -p 8080:18789).

npm: "node: not found" after Install

This usually means Node.js was installed but is not on your PATH. Run:

source ~/.bashrc
node --version

If it still fails, re-run the NodeSource setup script and ensure you're using the correct shell.

Docker: "Got permission denied"

Your user is not yet in the docker group. Run sudo usermod -aG docker $USER, then log out and log back in (or run newgrp docker in the current session).

Gateway Not Reachable from Outside the Server

Confirm ufw allows the port (sudo ufw status) and that your cloud provider's security group or firewall also allows inbound traffic on port 18789. AWS, GCP, and Hetzner all have separate network-level firewalls in addition to ufw.

systemd Service Fails to Start

Check the logs:

journalctl --user -u openclaw-gateway.service -n 50 --no-pager

Then run openclaw doctor, which checks your config, Node version and service and suggests fixes. A common cause is an unsupported Node version: OpenClaw 2026.9.8 needs Node 24.16 or newer within 24.x, or Node 26.1 or newer.

What's Next?

• Telegram setup — Connect your OpenClaw agent as a Telegram bot
• Discord setup — Add OpenClaw to your Discord server
• OpenRouter integration — Use any AI model via OpenRouter
• VPS hosting guide — Tips for running OpenClaw on a VPS long-term