How To Install OpenClaw on openSUSE

8 minutes read

If you want to run a self-hosted AI automation agent on a stable, production-grade Linux system, OpenClaw on openSUSE is one of the best combinations you can choose. OpenClaw is a free, open-source AI assistant that connects to messaging platforms like WhatsApp, Telegram, and Slack, then executes tasks on your behalf using AI models from providers like Google Gemini, OpenAI, and Anthropic. Unlike cloud-only tools, OpenClaw runs entirely on your own machine or server, which means you stay in control of your data, your environment, and your uptime. This guide walks you through how to install OpenClaw on openSUSE from a clean system all the way to a running, fully configured AI agent.

openSUSE is not Debian. It does not use apt. It uses zypper, an RPM-based package manager that handles dependency resolution differently from most tutorials you will find online. That is exactly why this guide exists: to give openSUSE users, whether on Leap or Tumbleweed, a precise, tested path through the installation process without having to mentally translate Ubuntu-centric instructions on the fly.

This article covers everything from updating your system and installing Node.js 22, to running the OpenClaw onboarding wizard, verifying the daemon, configuring your API key, troubleshooting common failures, and keeping your installation current.

Table of Contents

Prerequisites

Before you start, confirm your environment meets the following requirements.

Operating System:

openSUSE Leap 15.5, 15.6, or openSUSE Tumbleweed (latest rolling snapshot)

System Resources:

Minimum 1 vCPU and 1 GB RAM (2 GB RAM recommended for daemon-mode with active channels)
At least 10 GB of available disk space

Access and Permissions:

Root or sudo access to the machine
SSH access if you are working on a remote VPS

Required Tools (pre-install):

curl for downloading scripts and packages
git for source operations
gnupg for GPG key verification
ca-certificates for secure HTTPS connections

External Requirements:

An active internet connection
An API key from your preferred AI provider (Google Gemini, OpenAI, or Anthropic)

Security Note: The OpenClaw project itself warns against running it on a personal desktop machine with access to sensitive files. For production use, a dedicated VPS or isolated server is the right choice.

Step 1: Update Your openSUSE System

The first thing any sysadmin does before installing new software is bring the existing system fully up to date. Skipping this step creates dependency mismatches that are tedious to debug later.

Run the following two commands in sequence:

sudo zypper refresh
sudo zypper update

zypper refresh synchronizes your local repository metadata with the remote sources, making sure your package lists reflect the latest available versions. zypper update then upgrades all installed packages to their current releases. You may be prompted to confirm the update list; type y and press Enter to proceed.

On openSUSE Tumbleweed, this step is especially important because Tumbleweed is a rolling release. Running the update before adding new software ensures the base system is coherent.

Once the update completes, reboot the system if a kernel update was included:

sudo reboot

Step 2: Install Core System Dependencies

OpenClaw’s installer script expects a set of standard tools to be present before it runs. On a minimal openSUSE server installation, some of these may be missing.

Install them all in one command:

sudo zypper install -y git curl gnupg ca-certificates

Here is what each package does and why OpenClaw needs it:

git: Clones repositories and handles version-controlled components during setup
curl: Downloads the installation script and makes API calls during onboarding
gnupg: Verifies cryptographic signatures on packages and repository keys
ca-certificates: Ensures your system can validate SSL/TLS certificates when making HTTPS requests

Confirm the installs succeeded:

git --version
curl --version

Both commands should return version numbers without errors.

Step 3: Install Node.js 22 on openSUSE

OpenClaw is a Node.js application. It requires Node.js version 22 or higher to function correctly. Older versions will cause runtime errors during the openclaw onboard step, so this is not optional.

Check Your Current Node.js Version

First, check whether Node.js is already installed:

node --version

If the output shows v22.x.x or higher, skip to Step 4. If you see an older version, or if the command returns “command not found,” continue with the steps below.

Add the NodeSource Repository

openSUSE’s default repositories do not always carry Node.js 22, particularly on Leap. The NodeSource project provides a setup script that adds the correct RPM repository automatically.

Run the setup script:

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -

This script auto-detects that you are running an RPM-based distribution, adds the NodeSource repository to your zypper source list, and imports the GPG key for package verification. You will see output confirming each step.

Install Node.js via Zypper

With the NodeSource repository added, install Node.js 22:

sudo zypper install -y nodejs22

Verify the installation:

node --version
npm --version

Expected output:

v22.x.x
10.x.x

Both the Node.js runtime and npm (Node Package Manager) are now available. openSUSE Tumbleweed users may alternatively find Node.js 22 in the official rolling repositories and can install it directly with sudo zypper install -y nodejs22 without the NodeSource script.

Step 4: Install OpenClaw on openSUSE

Now you are ready to install the software itself. There are three supported methods. Each suits a different use case, so pick the one that fits your setup.

Method 1: Official Installer Script (Recommended)

The official installer script is the fastest and most reliable way to get OpenClaw running, especially on a fresh server. It handles the full stack automatically, from dependencies to the onboarding wizard.

Run:

curl -fsSL https://openclaw.ai/install.sh | bash

The script performs the following steps automatically:

Detects your operating system and package manager
Refreshes the package index
Installs Node.js 22 from NodeSource if not already present
Installs git, curl, gnupg, and ca-certificates
Installs the OpenClaw npm package globally
Launches the interactive onboarding text-based UI (TUI)

Once the script finishes its package installation phase, the onboarding TUI appears in your terminal. Read each prompt carefully before pressing Enter.

The wizard will walk you through:

Accepting the security disclaimer
Choosing Manual or Automatic onboarding mode (choose Manual for full control)
Setting the Gateway type to Local Gateway on loopback address 127.0.0.1
Confirming the workspace directory (default is fine)
Selecting your AI provider (Gemini, OpenAI, or Anthropic)
Entering your API key
Choosing the default AI model
Setting the Gateway port (default: 18789)
Configuring Gateway authentication (auto-generate a token)
Optionally configuring messaging channels like WhatsApp or Telegram
Installing the Gateway daemon service

Method 2: Manual NPM Installation

For users who want granular control over each installation step, the npm method works cleanly on openSUSE after Node.js 22 is installed.

Install the package globally:

npm install -g openclaw@latest

Run the onboarding wizard with daemon auto-start enabled:

openclaw onboard --install-daemon

The --install-daemon flag registers OpenClaw as a systemd service so it starts automatically on boot and restarts after a crash.

Verify the installation:

openclaw --version

Method 3: Docker

If you run containerized workloads on openSUSE, Docker gives you a fully isolated OpenClaw environment that does not touch the host system’s Node.js or npm setup.

Install Docker first if it is not already present:

sudo zypper install -y docker
sudo systemctl enable --now docker

Pull the official OpenClaw image:

docker pull openclaw/openclaw:latest

Run the container:

docker run -d --name openclaw -p 18789:18789 openclaw/openclaw:latest

Choosing Your Method

Method	Best For	Complexity
Official Script	First-time users, VPS deployments	Low
Manual NPM	Power users, custom environments	Medium
Docker	Containerized or multi-service setups	Medium-High

Step 5: Verify the Installation and Gateway Status

After installation, confirm that OpenClaw and its gateway daemon are running correctly.

Check the installed version:

openclaw --version

Check the gateway status:

openclaw gateway status

Expected output:

Gateway: enabled
Port: 18789
Bind: 127.0.0.1
PID: XXXXX
Dashboard: http://127.0.0.1:18789/?token=XXXXXXXX

The gateway is the entry point for all inbound traffic from your messaging channels. It runs as a systemd background service, routes messages to the correct agents, and manages session context.

If you are on a VPS and want to access the OpenClaw web UI from your local browser, create an SSH tunnel:

ssh -N -L 18789:127.0.0.1:18789 your-user@your-server-ip

Then open the tokenized dashboard URL in your browser.

To confirm the gateway is actively listening on the network level:

ss -pnltu | grep openclaw

You should see openclaw bound to 127.0.0.1:18789.

Step 6: Configure OpenClaw on openSUSE

With the installation confirmed, the next step is making sure your OpenClaw on openSUSE setup is production-ready. This means securing your API key, enabling the daemon, and setting up at least one messaging channel.

Set Your API Key Securely

OpenClaw stores its main configuration in ~/.openclaw/config.yaml. If you entered your API key during the onboarding wizard, it is already set. To verify or update it:

nano ~/.openclaw/config.yaml

Locate the api_key field and confirm it is populated. For better security, especially on systems where dotfiles may be synced to version control, use an environment variable instead:

export OPENCLAW_API_KEY="your_api_key_here"

Add that line to your shell profile to persist it:

echo 'export OPENCLAW_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrc

Enable and Manage the Systemd Service

If you used the --install-daemon flag or chose to install the Gateway service during onboarding, OpenClaw registers itself as a systemd unit. On openSUSE, manage it with the standard systemctl commands:

sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

For real-time log monitoring:

journalctl -u openclaw -f

Add a Messaging Channel

To connect WhatsApp, run the channel add wizard:

openclaw channels add

Select WhatsApp (QR Link), scan the QR code with your phone, and enter your full phone number including the country code. After pairing, list your connected channels:

openclaw channels list

Send a test message to confirm end-to-end connectivity:

openclaw message send --channel whatsapp --target "your-phone-number" --message "Hello from OpenClaw on openSUSE"

Configure the openSUSE Firewall

openSUSE enables firewalld by default. If the OpenClaw gateway is not reachable, add the required port:

sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

Verify the rule is active:

sudo firewall-cmd --list-ports

Troubleshooting Common Issues on openSUSE

Even a clean installation can run into environment-specific problems. Here are the five most common issues and how to fix them.

1. “openclaw: command not found” After Installation

This means the npm global binary directory is not in your shell’s PATH.

Find where npm puts global binaries:

npm config get prefix

Add it to your PATH:

export PATH=$PATH:$(npm config get prefix)/bin
echo 'export PATH=$PATH:'"$(npm config get prefix)"'/bin' >> ~/.bashrc
source ~/.bashrc

2. Node.js Version Below v22

If node --version returns anything below v22, the OpenClaw npm install will fail or produce unexpected runtime behavior.

Re-run the NodeSource script and reinstall:

curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo zypper install -y nodejs22
node --version

3. Permission Errors During Global npm Install

Global npm installs on openSUSE can fail with EACCES: permission denied when the npm prefix directory is owned by root.

Fix it by setting a user-local npm prefix:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=$PATH:~/.npm-global/bin
echo 'export PATH=$PATH:~/.npm-global/bin' >> ~/.bashrc
source ~/.bashrc

Then reinstall OpenClaw without sudo:

npm install -g openclaw@latest

4. Onboarding Wizard Does Not Appear

If the TUI wizard fails to render after running openclaw onboard, the terminal emulator may not support the interface. Avoid running the initial setup inside tmux or screen sessions.

Run it in a standard terminal such as Konsole, GNOME Terminal, or a direct SSH session:

openclaw onboard

If the issue persists, force a plain-text setup:

openclaw onboard --no-tui

5. Firewall Blocking the Gateway

If OpenClaw installs successfully but the web UI or messaging integrations fail to connect, firewalld is likely blocking the gateway port.

Open the required port:

sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --list-ports

Confirm 18789/tcp appears in the output.

Keeping OpenClaw Updated on openSUSE

OpenClaw is actively developed, and regular updates bring security patches, new skills, and improved channel integrations.

Always update your openSUSE base system first to avoid library mismatches:

sudo zypper refresh
sudo zypper update

Then update OpenClaw via npm:

npm install -g openclaw@latest

Check the new version:

openclaw --version

Restart the daemon to apply changes:

sudo systemctl restart openclaw

For Docker users, pull the latest image and recreate the container:

docker pull openclaw/openclaw:latest
docker stop openclaw && docker rm openclaw
docker run -d --name openclaw -p 18789:18789 openclaw/openclaw:latest

Congratulations! You have successfully installed OpenClaw. Thanks for using this tutorial for installing the latest version of OpenClaw on openSUSE Linux system. For additional help or useful information, we recommend you check the official OpenClaw website.

VPS Manage Service Offer

If you don’t have time to do all of this stuff, or if this is not your area of expertise, we offer a service to do “VPS Manage Service Offer”, starting from $10 (Paypal payment). Please contact us to get the best deal!