This guide explains how to install OpenClaw on Ubuntu 24.04 LTS on a desktop, headless server, or cloud VPS. You will install the current OpenClaw CLI, complete onboarding, register the Gateway as a user daemon, verify its health, and access the Control UI without unnecessarily exposing it to the internet.
OpenClaw runs a Gateway that connects an AI model with sessions, tools, files, messaging channels, and user interfaces. If you need the architecture and security model before installation, read What Is OpenClaw? A Complete Guide. This tutorial focuses on a single trusted operator and a cautious first installation.
Table of Contents
- Installation Overview
- Prepare Ubuntu
- Create a Dedicated User
- Check Node.js
- Install OpenClaw
- Run Onboarding
- Verify the Gateway
- Remote Access
- Send a Test Message
- Management Commands
- Update OpenClaw
- Files and Backup
- Troubleshooting
- Security Checklist
- Uninstall
- FAQ
Installation Overview
| Item | Requirement |
|---|---|
| Operating system | Ubuntu 24.04 LTS desktop, server, or VPS |
| Architecture | Use an architecture supported by Ubuntu, Node.js, and the current OpenClaw installer; verify unusual or legacy CPU platforms before installation |
| Node.js | 22.22.3+, 24.15+, or 25.9+; Node 23 is unsupported |
| Recommended runtime | Node.js 26; the official Linux installer provisions it when Node is missing or incompatible |
| Memory | No strict minimum is claimed here; size the host for the Gateway, selected tools, concurrency, and any local model |
| Model access | A supported hosted or local model provider and its documented authentication method |
| Privileges | Administrative access for Ubuntu preparation; run OpenClaw itself as a non-root user |
| Internet | Required for installation and for hosted model providers |
Step 1 — Prepare Ubuntu 24.04
Confirm the operating-system release using either command. cat is always present on a normal Ubuntu system; lsb_release may require the lsb-release package.
cat /etc/os-release
lsb_release -aRefresh package metadata, install available Ubuntu updates, and add the basic download and source-control tools:
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl ca-certificates gitcurl downloads the official installer, ca-certificates validates HTTPS certificates, and git supports source-based workflows and private workspace version control. Review upgrades and reboot first if Ubuntu reports that a kernel or critical library restart is required. Do not disable UFW, AppArmor, or another security control for this installation.
Step 2 — Create a Dedicated OpenClaw User
A persistent server or VPS should use a dedicated non-root account. It limits accidental access to another user’s files and gives the Gateway a clear ownership boundary.
sudo adduser openclaw
sudo loginctl enable-linger openclaw
sudo su - openclawLinger allows a systemd user service to continue after the account logs out. Ubuntu Desktop users may use their existing non-root account instead. Do not add the account to the docker or sudo group by default: either membership can provide powerful host access. If system preparation needs an administrator, perform that work separately and return to the unprivileged account before onboarding.
Step 3 — Check Node.js
node --version
npm --versionOpenClaw currently supports Node 22.22.3 or newer in the 22 line, Node 24.15 or newer, and Node 25.9 or newer, including Node 26. Node 26 is the recommended default; Node 23 is unsupported. You do not need to install Node manually before using the official installer because it detects an absent or incompatible runtime and provisions Node 26 on Linux.
If your organization manages Node itself, follow the current official Node setup guide. Its Ubuntu method currently uses the external NodeSource setup script. Review externally downloaded scripts before execution and use your organization’s package policy where applicable.
Step 4 — How to Install OpenClaw on Ubuntu 24.04
Method 1 — Official installer script
The recommended Linux installer detects the operating system, ensures a supported Node runtime, installs OpenClaw, and launches onboarding for an interactive unconfigured installation:
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bashPiping a remote script to a shell is convenient but leaves little time for review. To inspect the exact script first, download it to a private temporary location:
curl -fsSL --proto '=https' --tlsv1.2
https://openclaw.ai/install.sh
-o /tmp/openclaw-install.sh
less /tmp/openclaw-install.sh
bash /tmp/openclaw-install.shInspection can reveal obvious behavior but cannot guarantee complete safety. Confirm the HTTPS hostname, review changes when the installer updates, and use a disposable VM for initial evaluation.
Method 2 — Install through npm
Use npm only when you already manage a compatible Node version:
npm install -g openclaw@latest
openclaw --version
command -v openclawWith npm 12, OpenClaw’s official documentation notes that lifecycle scripts are blocked by default. If the normal command reports skipped scripts, follow the current documented form:
npm install -g openclaw@latest --allow-scripts openclawFor openclaw: command not found, open a new login shell and inspect the global prefix:
npm prefix -g
export PATH="$(npm prefix -g)/bin:$PATH"
command -v openclawAdd that export to ~/.bashrc only after confirming the path. If a global npm installation returns EACCES, use a user-owned prefix rather than running npm as root:
mkdir -p "$HOME/.npm-global"
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"Step 5 — Run OpenClaw Onboarding
openclaw onboard --install-daemonThe wizard configures model authentication, a workspace, Gateway settings, an optional messaging channel, a Gateway token, and the Linux systemd user service. Choose a supported provider or documented local model path; no single provider is mandatory.
If the chosen provider requires a key, obtain it from that provider and enter it only through the documented prompt or protected configuration. Use placeholders such as YOUR_MODEL_PROVIDER_API_KEY in documentation. Never place a real key in screenshots, shell history, logs, Git, chat, or WordPress content.
Step 6 — Verify the OpenClaw Gateway
openclaw gateway status
openclaw doctor
openclaw dashboardA healthy status normally reports a running supervisor and a successful connectivity probe. Current official getting-started documentation uses local port 18789, but use the URL and probe target printed by your actual status command because configuration and profiles can change it.
On Ubuntu Desktop, openclaw dashboard can open the Control UI in the default browser. On a headless server, copy neither the token nor internal URL into a public site; use the SSH tunnel described below.
The default Linux unit is currently openclaw-gateway.service. Confirm it before reading its journal:
systemctl --user list-units --type=service | grep -i openclaw
systemctl --user status openclaw-gateway.service
journalctl --user -u openclaw-gateway.service -fAccess OpenClaw Safely on a Remote Ubuntu Server
Do not expose the Gateway or dashboard directly to the public internet merely to finish setup. Prefer a loopback bind and forward it through SSH. First obtain the actual port from openclaw gateway status. Then run this command on your local workstation:
ssh -L LOCAL_PORT:127.0.0.1:GATEWAY_PORT user@server-ipReplace LOCAL_PORT with an unused port on your workstation and GATEWAY_PORT with the port printed by OpenClaw. Keep the SSH session open, then browse to http://127.0.0.1:LOCAL_PORT. This assumes the Gateway binds to loopback. Do not open the dashboard globally in UFW or bind it to 0.0.0.0 without authentication, a documented exposure design, and a rollback plan. A private VPN such as Tailscale is an optional alternative; follow OpenClaw’s current remote-access documentation.
Send a Test Message
Open the dashboard and begin with a read-only request:
List the files in the current OpenClaw workspace without modifying anything.Review the proposed action and result. Then test a narrow write inside the workspace:
Create a text file named openclaw-test.txt inside the workspace containing the current date.Verify the file manually with ls and cat, then remove it yourself if it is no longer needed. Do not use production credentials or destructive commands as an installation test.
Essential OpenClaw Management Commands
| Command | Purpose |
|---|---|
openclaw --version |
Show the installed CLI version. |
openclaw status |
Show a local summary of Gateway, service, sessions, providers, and update state. |
openclaw gateway status |
Inspect supervisor state and Gateway connectivity. |
openclaw gateway start |
Start the installed Gateway service. |
openclaw gateway stop |
Stop the Gateway service. |
openclaw gateway restart |
Restart the managed Gateway. |
openclaw dashboard |
Open the Control UI. |
openclaw doctor |
Check and repair configuration or state issues. |
openclaw logs --follow |
Follow current Gateway logs. |
openclaw security audit |
Audit filesystem, Gateway, tool, plugin, and exposure settings. |
openclaw update |
Update through the supported OpenClaw updater. |
openclaw --help |
List commands available in the installed release. |
How to Update OpenClaw on Ubuntu
The recommended updater coordinates code replacement with a managed Gateway service:
openclaw --version
openclaw update --dry-run
openclaw backup create --output "$HOME/Backups/openclaw" --verify
openclaw update
openclaw --version
openclaw gateway statusCreate the private backup destination first and protect it because the archive can contain credentials and channel state. The updater preserves state, configuration, credentials, and workspace. For a supervised npm installation, prefer openclaw update over a direct npm replacement because it can refresh service metadata and restart the Gateway. Use beta, extended-stable, or development channels only when you deliberately accept their documented stability trade-offs.
File Locations and Backup
Default configuration and state live under ~/.openclaw. The main configuration is ~/.openclaw/openclaw.json; credentials, SQLite state, agent data, sessions, skills, and service-related data also live under that private state tree. The default workspace is ~/.openclaw/workspace, although profiles and environment overrides can change these paths. Use openclaw config file and configuration commands to confirm the active path.
Use the supported backup command instead of copying a live collection of state files:
install -d -m 700 "$HOME/Backups/openclaw"
openclaw backup create --output "$HOME/Backups/openclaw" --verify
ls -la "$HOME/Backups/openclaw"Store archives in a protected destination and never commit ~/.openclaw to Git. The workspace may be backed up separately in a private repository, but remove secrets and keep state, credentials, and sessions outside it. Follow the official backup documentation for restoration because blindly replacing live SQLite files can lose newer state.
Common Installation Problems
| Problem | Likely cause | Safe fix |
|---|---|---|
openclaw: command not found |
npm global bin directory is absent from PATH | Run npm prefix -g, add its bin directory to PATH, and reopen the shell. |
| Unsupported Node version | Node is outside the supported ranges or is Node 23 | Use the official installer to provision Node 26 or follow the current Node guide. |
| npm global permission error | Global prefix is root-owned | Configure ~/.npm-global; do not solve it with blanket sudo or chmod 777. |
| Gateway daemon will not start | Invalid config, wrong service environment, stale install, or port conflict | Run openclaw gateway status --deep, openclaw doctor, and openclaw logs --follow. |
| Dashboard does not open on a VPS | No local browser or loopback-only Gateway | Use an SSH tunnel with the URL and port reported by Gateway status. |
| Model authentication fails | Expired, incorrect, restricted, or misplaced credential | Re-run provider configuration, verify account access, and avoid printing the secret. |
| Port already in use | Another process or stale Gateway occupies the configured port | Inspect openclaw gateway status --deep; resolve the duplicate instead of killing unrelated processes blindly. |
| Service stops after SSH logout | User lingering is disabled | As an administrator run sudo loginctl enable-linger openclaw, then inspect the user service. |
| Configuration permissions are too open | State was copied or created with incorrect ownership | Run openclaw security audit, inspect findings, and apply narrow owner permissions rather than recursive public access. |
| Installation works but model does not respond | Provider, selected model, network, quota, or context issue | Check openclaw status, provider configuration, logs, model availability, billing/quota, and network reachability. |
Basic Security Checklist
- Run OpenClaw as a non-root user on a clean host or isolated VM.
- Keep Ubuntu, Node, OpenClaw, plugins, and dependencies updated.
- Grant only the filesystem and network access required by approved workflows.
- Use restricted and rotatable API credentials where providers support them.
- Keep the Gateway private; use SSH tunneling or a secure VPN remotely.
- Back up important state and verify the backup.
- Review logs, actions, channel access, and security-audit findings.
- Treat email, web pages, documents, attachments, logs, and chat messages as untrusted input.
- Configure sandboxing and tool restrictions before enabling powerful host actions.
DevOps warning: do not initially provide root SSH keys, unrestricted Kubernetes cluster-admin credentials, production database passwords, cloud administrator tokens, or destructive GitLab CI/CD permissions. Start read-only, isolate the workspace, require human approval for consequential actions, and separate gateways across trust boundaries.
Uninstall OpenClaw
Preview the official uninstaller before removing anything:
openclaw uninstall --dry-run --allInteractive openclaw uninstall can remove selected service, state, workspace, and application scopes. State removal preserves configured workspace directories unless the workspace scope is also selected. To remove only the managed service and npm package while preserving user data:
openclaw gateway stop
openclaw gateway uninstall
npm rm -g openclawDestructive cleanup warning: do not delete ~/.openclaw or its workspace until you have confirmed the active paths and backed up everything required. If the dedicated Linux user is no longer needed, inspect its files and running processes before asking an administrator to remove that account. Never make user-data deletion an automatic uninstall step.
Conclusion
You now know how to install OpenClaw on Ubuntu 24.04, complete onboarding, run the Gateway as a systemd user daemon, verify health, and access the dashboard through a private path. Before granting broader tools or infrastructure access, complete the security audit, configure sandboxing and allowlists, establish backups, and test recovery.
Frequently Asked Questions
Can OpenClaw run on Ubuntu 24.04?
Yes. The official Linux installer supports Ubuntu-class Linux systems, and this guide targets Ubuntu 24.04 desktop, server, and VPS installations.
Does OpenClaw require Node.js?
Yes. The OpenClaw executable requires a supported Node runtime. The official installer provisions one when needed.
Which Node.js version does OpenClaw require?
Current documentation supports Node 22.22.3+, 24.15+, and 25.9+; Node 26 is recommended and Node 23 is unsupported.
Should OpenClaw run as root?
No for a normal single-user installation. Use a dedicated non-root user and elevate only narrowly scoped Ubuntu preparation tasks.
Can OpenClaw run on an Ubuntu VPS?
Yes. Keep the Gateway private, enable the user service to survive logout, and use an SSH tunnel or documented private VPN access.
How do I access the dashboard remotely?
Read the port from openclaw gateway status and forward the loopback address through SSH. Do not expose the dashboard port publicly just for convenience.
How do I update OpenClaw on Ubuntu?
Create a verified backup, preview with openclaw update --dry-run, run openclaw update, and verify the version and Gateway afterward.
Where does OpenClaw store its configuration?
The default config is ~/.openclaw/openclaw.json, with state and credentials under ~/.openclaw. Overrides and profiles can change the active paths.
Can I install OpenClaw without running the remote installer?
Yes. With a compatible Node runtime, install the published package using npm install -g openclaw@latest.
How do I uninstall OpenClaw?
Start with openclaw uninstall --dry-run --all. Remove only the intended service, application, state, or workspace scopes and preserve user data unless deletion is deliberate.
