Install OpenClaw on Linux: a safer Node and Gateway checklist
To install OpenClaw on Linux, start with the supported installer, let it select a compatible runtime when Node is missing, complete onboarding, and verify the Gateway before adding channels or automations. The simple path is usually the safest one because a half-managed Node installation is harder to diagnose than a clean, supported install.
The official installer is the right default for a new Linux machine:
curl -fsSL https://openclaw.ai/install.sh | bashThat command detects the operating system, installs Node when needed, installs OpenClaw, and launches onboarding. Decide first whether this host is a workstation, a Linux VPS, or a remote Gateway.
Table of contents
- Choose the right Linux install path
- Why the Node runtime deserves a check
- Install OpenClaw on Linux without mixing ownership
- Verify the Gateway before adding channels
- Use a systemd user service deliberately
- FAQ
Choose the right Linux install path
OpenClaw supports several Linux entry points. They solve different problems. Pick one primary path rather than combining a global npm install, a local-prefix install, and a desktop companion on the same host.
| Situation | Best starting point | Why |
|---|---|---|
| New Ubuntu, Debian, Fedora, or VPS host | Official installer | Detects Linux, provisions a compatible Node runtime when missing, then starts onboarding |
| You already manage Node for this user | npm, pnpm, or Bun route in the official install docs | Keeps runtime ownership with your existing toolchain |
| You want a private managed install under your home directory | install-cli.sh local-prefix installer | Avoids depending on a system-wide Node installation |
| You want a local or remote GUI route | Linux desktop companion | Handles local setup or connects to a known remote Gateway |
| You are contributing from source | Source build instructions | Uses the repository’s pinned package-manager workflow |
The official install overview lists Node 22.22.3+, 24.15+, or 25.9+ as supported and notes that Node 26 is recommended generally. On Linux, the installer provisions Node 24 LTS if Node is missing. That is a useful distinction: do not replace the installer-managed runtime with an arbitrary prerelease just because it is newer.
If your aim is a self-hosted assistant rather than a development environment, the lowest-maintenance route is usually a dedicated Linux user, one install path, one Gateway, and a place for its state. What is OpenClaw? explains the product boundary; how OpenClaw works is the useful companion reading before you expose the Gateway to channels and tools.
Why the Node runtime deserves a check
A Node version is not decoration. It controls whether the CLI starts, whether native dependencies resolve, and whether later updates land on the runtime the release expects.
The OpenClaw 2026.9.1-beta.1 release notes call out a Linux installer fix: fresh Linux setup provisions stable Node 24 LTS and scopes RPM installation to the configured NodeSource repository, preventing an incompatible prerelease from being selected. That change is a reminder to avoid treating a working node --version as the whole validation story. The runtime must also come from a path that your install method expects and can update cleanly.
Before installation, the useful questions are modest:
- Does this user already own a Node toolchain for other projects?
- Is this a package-managed Linux host, a container, or a throwaway VPS?
- Do you need a global CLI, or would a local prefix under
~/.openclawbe easier to own? - Will the Gateway run continuously under a systemd user service?
The NodeSource distributions repository is relevant only when you are deliberately managing Node packages yourself. It is not a reason to add another repository to a host where the OpenClaw installer already handled Node. More package sources mean more update paths to audit.
For a Windows machine using Linux through WSL, keep that environment separate from native Windows tooling. The existing OpenClaw WSL setup guide covers that boundary. A WSL instance is Linux for the Gateway, but it still has its own service lifecycle and filesystem constraints.
Install OpenClaw on Linux without mixing ownership
A clean new-host sequence is short:
- Use a normal, non-root user for the agent runtime.
- Run the supported installer.
- Complete the provider and Gateway choices in onboarding.
- Verify the CLI and Gateway before you connect a chat channel.
- Decide whether managed startup is appropriate for this host.
The first four checks are concrete:
openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboardopenclaw --version confirms that the shell can find the CLI. openclaw doctor checks configuration issues. openclaw gateway status confirms that the Gateway service is reachable. openclaw dashboard opens the Control UI so you can confirm that the control surface, authentication, and selected model work together.
If openclaw is not found after a successful install, do not reinstall immediately. The official troubleshooting guidance starts with node -v, npm prefix -g, and the current PATH. A duplicate installation often turns a simple PATH problem into two competing installations.
The installer also supports --no-onboard for an automation workflow that must defer interactive setup:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboardUse that only when you have a later, explicit onboarding step. Installing the CLI without deciding how the Gateway will authenticate is not a finished deployment.
Verify the Gateway before adding channels
A Linux install is operational when the Gateway has a known owner, an expected runtime, a working model credential, and a confirmed status. It is not operational merely because a package command returned zero.
The current getting-started documentation says a healthy Gateway listens on port 18789. You do not need to publish that port to the internet to test it. Start with the local dashboard, then use a trusted network, SSH tunnel, or the documented remote-access route when another device needs to connect.
This order avoids a common debugging trap. If a Telegram, Discord, or Slack connection fails before the Gateway itself has been checked, it is easy to blame the channel token while the real fault is a missing runtime, a stopped user service, or a wrong local endpoint. The Gateway architecture overview and why self-hosted ownership matters are useful context for this division of responsibility.
For a Linux desktop companion, the platform documentation says it can install missing prerequisites into a private managed runtime, attach to a healthy Gateway before service changes, and manage the CLI-owned systemd user service. It can also connect to a remote Gateway over an SSH tunnel. That is a valid alternative to a terminal-only setup, not an extra layer to add on top of an already stable manual installation.
Use a systemd user service deliberately
For Linux and WSL2, OpenClaw can install managed startup through openclaw onboard --install-daemon or openclaw gateway install. The install documentation describes this as a systemd user service.
A user service is a sensible default for a personal agent because it keeps the agent’s state, credentials, and lifecycle tied to the account that owns them. It also changes the questions you should answer during incident response:
| Check | Why it matters |
|---|---|
| Which Linux user owns the service? | It determines the home directory, PATH, state path, and credentials available to the Gateway |
| Did the user service start after reboot? | A shell session and a long-running service have different startup behavior |
| Is the expected Node runtime visible to that service? | An interactive shell can have a different PATH from systemd |
| Is the Gateway local or remote? | Remote access needs its own authentication and transport controls |
Do not copy a system-wide service file from an old tutorial just to get persistence. The current OpenClaw documentation describes the supported user-service route. It is easier to update and less likely to run the agent with an unexpected root-owned state directory.
FAQ
What Node version should I use to install OpenClaw on Linux?
The install documentation supports Node 22.22.3+, 24.15+, or 25.9+, and lists Node 26 as the general recommendation. When Node is missing on Linux, the official installer provisions Node 24 LTS. Follow the installer or the documented package-manager path instead of selecting a prerelease on your own.
Can I install OpenClaw on a Linux VPS?
Yes. The official documentation includes a Linux server and VPS deployment path. Treat a VPS as a service host: use a dedicated user, verify the Gateway locally first, and choose remote access controls before exposing a dashboard or channel connection.
Should I use npm, pnpm, Bun, or the installer script?
Use the installer script for a new host unless you already intentionally manage the Node environment. Use npm, pnpm, or Bun only when you want the runtime and package-manager lifecycle to remain under your own toolchain. Avoid mixing these paths on the same user account.
Why does openclaw say command not found after installation?
The official install guide says this is usually a PATH issue. Check the Node runtime, your global npm prefix, and the shell PATH before reinstalling. A second installation can hide the original problem.
Do I need to expose Gateway port 18789 publicly?
No. Verify the Gateway locally first. For remote use, prefer the documented remote-access controls, SSH tunneling, or a trusted private network rather than publishing an unauthenticated local endpoint.
Sources: OpenClaw install overview, OpenClaw Linux platform guide, OpenClaw getting started, OpenClaw v2026.9.1-beta.1 release notes, NodeSource distributions.