Running an AI assistant on a third-party cloud platform means your conversations, API keys, and agent logic all live on someone else’s hardware. If that bothers you as much as it bothers me after a decade of managing Linux servers, then learning how to install OpenClaw on Ubuntu 26.04 is a practical step toward keeping your stack under your own control.

OpenClaw is a self-hosted AI gateway. It routes agent sessions, tool calls, memory, and messaging channels like WhatsApp, Telegram, and Discord through your own server instead of a managed cloud service. Ubuntu 26.04 LTS ships with Kernel 7.0, carries a long upstream support window, and is one of the primary targets OpenClaw’s installer scripts are actively tested against — which makes it a solid base for this kind of deployment.

This guide walks through every step to get OpenClaw on Ubuntu 26.04 setup and running: three installation methods, onboarding, systemd persistence, UFW firewall rules, security hardening, updates, and the most common errors you will hit on the first day. By the end, you will have a live OpenClaw gateway with a browser dashboard you can reach over SSH tunnel or a public IP, depending on your setup.

Prerequisites: What You Need Before You Start

Before you run a single command, confirm you have everything below in place. Skipping any of these is the fastest way to get a half-broken install that is annoying to debug.

Hardware minimums:

• 2 vCPU (1 core works but creates I/O bottlenecks under concurrent agent requests)
• 4 GB RAM (2 GB absolute minimum; the gateway process alone consumes 800 MB to 1.5 GB during initialization)
• 20 GB SSD storage (npm packages, session logs, and workspace files accumulate quickly; an HDD introduces I/O wait under load)

Software requirements:

• Ubuntu 26.04 LTS — clean install or an existing server with no conflicting Node.js installation
• A sudo-capable user account (not root)
• curl installed (minimal and server editions often skip it)
• At least one AI provider API key from Anthropic, OpenAI, or Google (OpenClaw is the routing gateway; it needs a backend provider to generate actual AI responses)

System requirements at a glance:

Step 1: Choose Your Installation Method

Ubuntu 26.04 does not publish an openclaw package in its default repositories. Running apt-cache policy openclaw returns nothing. OpenClaw ships through three upstream paths, and picking the right one before you start saves you from messy PATH conflicts and permission errors later.

WHY this matters: The three methods place the binary in different directories, manage Node.js differently, and update through slightly different mechanisms. Installing the wrong method for your environment — especially on a shared or production server — creates subtle problems that are tedious to untangle.

Your three options:

Use the official installer if this is a fresh VPS or server and you want OpenClaw to handle Git and Node.js for you.

Use the local-prefix installer if you manage a shared server where system-wide Node.js changes are not acceptable.

Use manual npm if you already run nvm or NodeSource and only want the OpenClaw package on top of your existing runtime.

Step 2: Install OpenClaw on Ubuntu 26.04 Using the Official Installer

This is the fastest and most reliable path for most people reading this. The official installer handles Git, Node.js 22, and npm prefix configuration automatically, and it leaves future updates under the openclaw update workflow.

Step 2.1: Install curl and update the package index

sudo apt update
sudo apt install curl -y

WHY: Running apt update before any install syncs your local package list with Ubuntu’s mirrors. Without it, apt may attempt to install an outdated version of curl or fail to locate it entirely. Server and minimal Ubuntu images frequently ship without curl preinstalled, so this step is not optional even if you think it is already there.

Step 2.2: Run the official bootstrap script

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard

WHY: The --proto '=https' --tlsv1.2 flags enforce a TLS 1.2+ connection so the install script cannot be intercepted or downgraded over the network. The --no-onboard flag separates installation from configuration, which makes this command safe to run from SSH sessions, cloud-init scripts, and automation pipelines where interactive prompts would stall or fail.

Expected output:

Install plan
OS: linux
Install method: npm
Requested version: latest
Onboarding: skipped

[1/3] Preparing environment
Node.js not found, installing it now
Node.js v22.x.x installed

[2/3] Installing OpenClaw
npm configured for user installs
Installing OpenClaw v2026.x.x
OpenClaw npm package installed

[3/3] Finalizing setup
OpenClaw installed successfully!
Skipping onboard (requested); run openclaw onboard later

Step 2.3: Fix the PATH if the shell does not find the binary

grep -qxF 'export PATH="$HOME/.npm-global/bin:$PATH"' ~/.bashrc || printf '%s\n' 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
hash -r

WHY: The installer places the openclaw binary inside your npm global bin directory, which Ubuntu does not include in $PATH by default. Without this step, running openclaw returns “command not found” even though the binary exists on disk. The grep guard prevents duplicate PATH entries if you run this command more than once.

If you use zsh, swap ~/.bashrc for ~/.zshrc in the above command.

Step 2.4: Confirm the binary responds

openclaw --version

Expected output:

OpenClaw 2026.x.x (short-hash)

WHY this verification matters: A version check confirms the binary is on your PATH, the installer completed without silent errors, and you have a baseline version number. If this command fails, solve it now before moving to onboarding — do not skip ahead.

Step 3: Alternative — Local-Prefix Installer (Contained User-Space)

If you are on a shared server or you want no system-level Node.js changes, the local-prefix installer keeps the CLI, a bundled Node.js 22 runtime, and all related files under ~/.openclaw. Skip this section if you used the official installer in Step 2.

Step 3.1: Run the local-prefix script

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash

WHY: This script downloads a bundled Node.js 22 runtime and installs everything inside ~/.openclaw. It does not touch system-level Node.js or your npm global directory. This is the right call for multi-user servers where affecting other users’ runtimes is not acceptable.

Step 3.2: Add the binary to your PATH

grep -qxF 'export PATH="$HOME/.openclaw/bin:$PATH"' ~/.bashrc || printf '%s\n' 'export PATH="$HOME/.openclaw/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.openclaw/bin:$PATH"
hash -r

Verify:

openclaw --version

Step 4: Alternative — Manual npm Install (Existing Node.js Workflows)

Use this path only if you already manage your own Node.js runtime through nvm or NodeSource. Skip to Step 5 if you completed Step 2 or Step 3.

Step 4.1: Install Node.js 22 via NodeSource

sudo apt install -y curl build-essential
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version && npm --version

WHY: Ubuntu 26.04’s default repositories may not carry Node.js 22 or higher. OpenClaw requires Node 22.14+ at minimum. Using NodeSource guarantees you get a supported, maintained version directly from the Node.js maintainers rather than whatever Ubuntu packages at release time.

Step 4.2: Set a writable npm global prefix

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"

WHY: npm’s default global prefix on Ubuntu points to /usr, a root-owned directory. Attempting a global install as a normal user produces an EACCES: permission denied error. Moving the prefix to your home directory means you never need sudo for global npm installs, which is safer and avoids broken permission chains.

Step 4.3: Export the new PATH and install OpenClaw

grep -qxF 'export PATH="$HOME/.npm-global/bin:$PATH"' ~/.bashrc || printf '%s\n' 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
export PATH="$HOME/.npm-global/bin:$PATH"
hash -r
npm install -g openclaw@latest
openclaw --version

WHY @latest: This tag forces npm to pull the newest stable release rather than a cached or stale registry entry on your local machine.

Step 5: Run Onboarding and Configure the Gateway

Installing the CLI binary only gives you a command on disk. Onboarding is the step that writes ~/.openclaw/openclaw.json, builds the ~/.openclaw/workspace directory, stores your provider credentials, and installs the systemd user service that keeps the gateway alive between sessions.

WHY this is a separate step: Separating install from configuration makes the bootstrap scriptable and repeatable. You can install the binary via automation and run onboarding interactively later — or non-interactively in CI pipelines.

Step 5.1: Standard interactive onboarding

openclaw onboard --install-daemon

This walks you through provider credentials (Anthropic, OpenAI, or Google API key), gateway auth mode, and channel setup. The --install-daemon flag registers OpenClaw as a systemd user service so the gateway survives SSH logouts and reboots.

Step 5.2: Non-interactive onboarding for headless servers

openclaw onboard --non-interactive --accept-risk \
  --skip-channels --skip-skills \
  --skip-search --skip-ui \
  --install-daemon \
  --gateway-bind loopback \
  --gateway-auth token \
  --gateway-token your-local-dashboard-token

WHY: On a headless VPS, interactive prompts either fail or stall indefinitely. This command completes first-run configuration without any keyboard input, making it safe for automation, cloud-init scripts, and SSH-only environments. Replace your-local-dashboard-token with a strong random string.

Step 5.3: Enable systemd lingering

sudo loginctl enable-linger "$USER"

WHY this is critical: Without lingering, Ubuntu’s systemd destroys all user services the moment you log out of an SSH session — even if the service is technically “enabled.” Lingering keeps the user service scope alive independently of active login sessions, so OpenClaw keeps running after you disconnect.

Step 6: Verify the Gateway and Access the Dashboard

Step 6.1: Check gateway status

openclaw gateway status

Expected output:

Service: systemd (enabled)
Service file: ~/.config/systemd/user/openclaw-gateway.service
Gateway: bind=loopback (127.0.0.1), port=18789
Runtime: running (pid 23042, state active)
RPC probe: ok
Listening: 127.0.0.1:18789

WHY this command first: It confirms the systemd user service is active, the correct port is bound, and the RPC probe responds — all before you open a browser. Skipping this and going straight to the browser wastes time when the service is not actually running.

Step 6.2: Print the tokenized dashboard URL

openclaw dashboard --no-open

Expected output:

Dashboard URL: http://127.0.0.1:18789/#token=your-local-dashboard-token
Browser launch disabled (--no-open). Use the URL above.

WHY --no-open: Navigating directly to http://127.0.0.1:18789 without the token fragment drops you on a connect screen that prompts for credentials. The tokenized URL drops you straight into the authenticated dashboard. On a headless server, this flag also prevents OpenClaw from trying to open a browser that does not exist.

Key file locations you should know:

Step 7: Configure the UFW Firewall

Configuring the firewall is not optional if your Ubuntu 26.04 server has a public IP address. OpenClaw’s gateway defaults to 127.0.0.1 (loopback) for local installs, but any change to the bind address without proper firewall rules exposes an unauthenticated port to the open internet.

sudo ufw allow ssh
sudo ufw allow 18789/tcp
sudo ufw enable
sudo ufw status

WHY allow SSH first: Enabling UFW without an explicit SSH rule locks you out of your server permanently on a remote VPS. Always add the SSH rule before ufw enable.

For tighter production security, restrict by source IP:

sudo ufw allow from YOUR_IP_ADDRESS to any port 18789

WHY: Limiting dashboard access to your specific IP reduces the attack surface to near zero even if port 18789 is open at the network level. Anyone else scanning the port gets silently dropped.

Step 8: Security Hardening

A running gateway on a public-facing server needs a few more layers beyond the firewall. These are the steps applied on every OpenClaw deployment worth protecting.

Create a dedicated system user

sudo useradd -m -s /bin/bash openclaw

WHY: Running OpenClaw as your personal account means a compromised process inherits your full file system permissions. A dedicated openclaw user limits the blast radius of any vulnerability.

Restrict API key file permissions

chmod 600 ~/openclaw/.env

WHY: The .env file holds your Anthropic, OpenAI, or Google API keys. World-readable permissions mean any process or local user on the system can read and extract them. 600 limits access to the file owner only.

Enable automatic security updates

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

WHY: OpenClaw runs on a Node.js runtime and system packages that receive regular security patches. Unattended upgrades ensure the underlying system stays patched without requiring your manual intervention after every Ubuntu security advisory.

Install fail2ban

sudo apt install -y fail2ban
sudo systemctl enable --now fail2ban

WHY: Fail2ban monitors auth logs and bans IP addresses that generate excessive failed login attempts. On any public-facing server, SSH brute-force attacks are a constant background noise. Fail2ban cuts that noise off automatically.

Step 9: Keep OpenClaw Updated

OpenClaw ships its own updater, so use it rather than mixing npm and apt commands after the initial install.

Preview the update first

openclaw update --dry-run

WHY dry-run first: The output shows your current version, the target version, and every planned action including gateway restarts. Reviewing this before applying prevents surprise downtime during active agent sessions.

Apply the update

openclaw update

Switch to the beta channel

openclaw update --channel beta --dry-run
openclaw update --channel beta

WHY preview a channel switch: The dev channel converts a package install into a git checkout, which changes update behavior significantly. Always dry-run before switching channels on a production server.

Troubleshooting: 5 Common Issues on Ubuntu 26.04

Issue 1: openclaw: command not found

This means the binary exists on disk but its parent directory is not in your $PATH. Check which prefix was used:

npm prefix -g
echo "$PATH"

Add the correct export line and reload:

export PATH="$HOME/.npm-global/bin:$PATH"
hash -r
openclaw --version

WHY this happens: The installer places the binary in a non-standard directory that Ubuntu’s default shell does not scan automatically. The fix is always a PATH update — not a reinstall.

Issue 2: npm error EACCES: permission denied

mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
npm install -g openclaw@latest

WHY: npm tries to write to /usr/lib/node_modules on Ubuntu by default. That directory is root-owned. Moving the prefix to your home directory sidesteps this entirely without using sudo npm, which creates its own problems.

Issue 3: Dashboard connects but drops to the login screen

openclaw dashboard --no-open

Copy the full tokenized URL from the output and open it directly. Do not navigate to http://127.0.0.1:18789 without the #token= fragment.

WHY: The Control UI distinguishes between the bare URL (shows the connect screen) and the tokenized URL (bypasses it). Always use the tokenized URL.

Issue 4: No API key found for provider

Rerun onboarding and complete the provider credential prompts:

openclaw onboard --install-daemon

WHY: This error confirms the gateway is working correctly. The missing piece is agent authentication, not the gateway itself. Re-running onboarding stores your API key in ~/.openclaw/openclaw.json where the agent process can read it.

Issue 5: Gateway stops every time you log out

sudo loginctl enable-linger "$USER"

WHY: Systemd destroys user service sessions when the user logs out, by design. The enable-linger command keeps the user’s service manager slice alive even with no active login sessions. This is the most common issue on fresh VPS setups and the fix is a single command.

Quick diagnostic reference:

Congratulations! You have successfully installed OpenClaw. Thanks for using this tutorial for installing the OpenClaw Personal AI Assistant on your Ubuntu 26.04 LTS (Resolute Racoon) system. For additional help or useful information, we recommend you check the official OpenClaw website.