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 20+ (Node 22 LTS is preferred)
• 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 20+ installed first.

1. Install Node.js 22 LTS using NodeSource:

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

2. Install OpenClaw globally:

   sudo npm install -g openclaw

3. Create the credentials directory (required for pairing mode):

   mkdir -p ~/.openclaw/credentials

4. Start the gateway:

   openclaw gateway --allow-unconfigured

5. Open http://localhost:18789 in your browser to access the web gateway and configure your AI model and chat channels.

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. Create a config directory:

   mkdir -p ~/openclaw/credentials

4. Pull and run the OpenClaw container:

   docker run -d \ --name openclaw \ --restart unless-stopped \ -v ~/openclaw:/home/node/.openclaw \ -p 18789:18789 \ ghcr.io/openclaw/openclaw:latest \ node openclaw.mjs gateway --allow-unconfigured

5. Verify the container is running:

   docker ps docker logs openclaw

The --restart unless-stopped flag means Docker will automatically restart OpenClaw after a server reboot.

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:

   npm install npm run build

4. Run OpenClaw:

   node dist/openclaw.mjs gateway --allow-unconfigured

Ubuntu-Specific Tips

Run OpenClaw as a systemd Service

For production deployments, run OpenClaw as a systemd service so it starts automatically on boot and restarts on failure.

Create the service file:

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

Paste the following (replace YOUR_USER with your username):

[Unit] Description=OpenClaw AI Agent After=network.target [Service] Type=simple User=YOUR_USER WorkingDirectory=/home/YOUR_USER ExecStart=/usr/bin/openclaw gateway Restart=on-failure RestartSec=5 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 sudo systemctl status openclaw

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:

sudo journalctl -u openclaw -n 50 --no-pager

Common causes: wrong path to the openclaw binary, missing ~/.openclaw/credentials directory, or the config file has a JSON syntax error.

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