VPS Tutorials
How to Install OpenClaw on a VPS (2026): Ubuntu Cloud Server Deployment, SSH Tunnel Access, and Common Errors
If you want to run OpenClaw on a cloud server long term, the key is not just typing the commands, but getting the runtime, background service, access method, and security boundary right in one pass. This article follows the actual deployment flow on an Ubuntu VPS and walks you through installing OpenClaw, starting the daemon, accessing it via SSH tunnel, basic verification, and troubleshooting common errors.
If you want OpenClaw running online 24/7, deploying it to a VPS is usually more stable than keeping it on your local computer.
The official documentation already supports this path fairly completely: a Linux VPS can run the OpenClaw Gateway directly, and you can access the control interface from your laptop through an SSH tunnel or another controlled method. The benefit is that the workspace, state, and background service all stay on the server, so they won't be interrupted when you close your laptop or your local network fluctuates.
This article is written for a typical Ubuntu VPS, with a clear goal:
- Install OpenClaw on a cloud server
- Keep the Gateway running persistently as a background service
- Access the control interface securely from a local browser
- Handle the most common errors during installation along the way
Before you start, you need at least the following:
- An Ubuntu VPS
- A regular user that can log in via SSH
- The server can access the internet normally
- Your local computer can also use the
sshcommand
According to the official FAQ, the minimum requirements for OpenClaw on a VPS are not high, but it's better to prepare a machine with at least 1-2 vCPU / 2GB RAM. Prefer Ubuntu LTS or a Debian-based distribution for the OS.
If you're just trying it out, a low-spec machine can start it; if you plan to attach more channels and run more workspaces later, it's better not to be too tight on memory from the start.
First, log in to the server:
ssh your-user@your-server-ip
Once connected, do a system update first:
sudo apt update && sudo apt upgrade -y
Then install some basic tools:
sudo apt install -y curl git unzip ca-certificates
This step looks ordinary but is important. Many subsequent installation failures are essentially caused by the system being too old, incomplete certificates, or missing basic commands like curl and git.
OpenClaw officially recommends Node 24 at present, and is also compatible with the newer Node 22 LTS. For a VPS, the most reliable approach is to install a newer officially supported version directly, rather than continuing to use the possibly older Node from the Ubuntu software repositories.
If Node is not yet installed on your machine, check first:
node -v
npm -v
If it's not installed, or the version is too old, you can install Node 24 via NodeSource:
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
After installation, confirm the version again:
node -v
npm -v
If the output here is Node 24, you can continue.
If you want the shortest path, you can run the official install script directly:
curl -fsSL https://openclaw.ai/install.sh | bash
This approach suits people who want to get it running as quickly as possible.
If you prefer to control every step yourself, you can also install globally with npm directly:
npm install -g openclaw@latest
After installation, confirm the command is available:
openclaw --version
If the version number is output normally here, the CLI installation was successful.
The officially recommended initialization entry point for OpenClaw is not manually piecing together a bunch of configuration, but running directly:
openclaw onboard --install-daemon
This command will guide you through the initial configuration and install the Gateway as a background service along the way.
You can think of it as doing two things at once:
- Completing OpenClaw's first configuration
- Registering the Gateway as a systemd user-level service so it keeps running after you exit the terminal
During this process, you'll typically encounter these key inputs:
- Gateway listening port
- Access authentication method
- Shared secret or token
- Initialization configuration for the workspace or profile
It's recommended to note down the token or password first, as you'll need it when accessing from a local browser later.
After initialization, don't rush to open the interface locally; first confirm the service status on the server.
You can check the process or service first:
systemctl --user status openclaw-gateway
If your service name has a profile suffix, it might also be a name like this:
systemctl --user status openclaw-gateway-yourprofile
If you want to see the logs:
journalctl --user -u openclaw-gateway -f
Or the service name corresponding to your own profile.
Normally, you should see that the Gateway is listening on the default port 18789 and the service status is running.
If the previous installation flow did not install successfully automatically, you can also run it manually again:
openclaw gateway install
Or run again:
openclaw doctor
The official documentation also treats doctor as the first troubleshooting entry point for repair and migration scenarios.
This is the most critical step in VPS deployment, and also the most easily overlooked.
Many people, once the service is installed, want to expose port 18789 directly to the public internet. But the officially recommended approach is to first let the Gateway listen only on the local loopback address, then access it from your own computer via an SSH tunnel.
Run this on your local computer:
ssh -N -L 18789:127.0.0.1:18789 your-user@your-server-ip
This command means:
- Forward your local
127.0.0.1:18789 - To
127.0.0.1:18789on the VPS
Then open in your local browser:
http://127.0.0.1:18789/
You'll see the OpenClaw control interface, then enter the token or password configured during the openclaw onboard stage.
The advantages of this path are very direct:
- No need to expose the management port directly to the public internet
- Clearer security boundary
- Suitable for long-term use by individuals or small teams
If you really need longer-term remote access later, consider Tailscale or other more complete network solutions, which would be more reasonable.
Being able to open the control interface doesn't mean the installation is fully usable; you should do another layer of verification.
You can test the following commands on the server:
openclaw doctor
If you just want to confirm whether the Gateway can start in the foreground, you can also run temporarily:
openclaw gateway --port 18789 --verbose
If you've already completed model or channel-related configuration, you can continue with further functional verification, such as sending a test message or starting a simple agent conversation.
But for an installation tutorial, this step is enough to determine:
- Node environment is normal
- OpenClaw CLI is available
- Gateway has been deployed successfully
- Local access via SSH tunnel works securely
If you're just trying it out for the first time, the Node + npm + onboard approach above is enough.
But if you plan to run OpenClaw as a long-term persistent service on a VPS, the Docker route is also worth considering, especially in the following situations:
- You want a more unified way of running things
- You already have existing Docker operations habits
- You want to manage data directories and upgrade processes more clearly
The official documentation already provides a Docker Compose solution for the Hetzner scenario, with the core idea of persisting these directories:
~/.openclawworkspace- Possibly other runtime cache directories as well
If you later want to write a more production-oriented deployment plan, you can absolutely extend this article into an "OpenClaw Dockerized Deployment" article.
This usually means the global npm install directory is not in the current shell's PATH, or the installation simply didn't succeed.
Check first:
npm root -g
npm bin -g
Then confirm whether the corresponding directory has been added to PATH.
If you installed via the install script, it's also recommended to open a new shell session and try again.
If you see a runtime error, check the Node version first thing:
node -v
OpenClaw officially recommends Node 24 at present. The Node in Ubuntu's default repositories is often too old, and it's not recommended to use it directly.
In this case, prioritize checking 3 things:
- Whether the Gateway on the VPS is actually running
- Whether your SSH tunnel command is still connected
- Whether the port is written incorrectly
The most common problem is not that OpenClaw didn't start, but that you closed the SSH session, causing the local forwarding to become invalid.
Technically possible, but not recommended to do so right away.
If you haven't clearly limited the authentication mode, listening address, and access source, you're essentially exposing the management plane directly. For personal deployments, an SSH tunnel is usually enough.
If you only ran openclaw gateway --port 18789 in the foreground, then of course it stops after you exit the shell.
For long-term running, you should use:
openclaw onboard --install-daemon
Or:
openclaw gateway install
Then use systemctl --user to confirm the service status.
If you just want to get OpenClaw running on a VPS, the most reliable path is actually not complicated:
- Prepare an Ubuntu VPS
- Install Node 24
- Install the OpenClaw CLI
- Run
openclaw onboard --install-daemon - Access
127.0.0.1:18789via SSH tunnel
This path is more suitable for most individual users than "exposing the public port directly," and is also more in line with OpenClaw's official recommendation for VPS deployment.
If you plan to run it long term, connect multiple devices, or attach more automation tasks later, continuing with Dockerization, remote access, and backup strategies will be more stable.
The most practical next step is not to keep reading tutorials, but to actually get your own VPS running first, then use openclaw doctor to do a complete check.