Install OpenClaw on Linux

Run the self-hosted AI agent on Ubuntu, Debian, Fedora, Arch Linux, or any Linux distro with Node.js 22+. This guide covers the one-line installer, optional manual install, and running OpenClaw as a systemd service so it starts on boot.

📘 Quick path: For the fastest setup (~5 min), use the Quick Start Guide. This page is the full Linux-specific reference.

1. Overview

OpenClaw runs natively on Linux and is widely used on servers, VPS, and desktops. This guide covers:

  • System requirements and supported distributions
  • One-line installer (recommended) and manual installation
  • Distro-specific notes (Ubuntu, Debian, Fedora, Arch)
  • Running OpenClaw as a systemd service (auto-start on boot)
  • Common issues and troubleshooting
  • Security and next steps

2. Prerequisites

  • OS: Ubuntu 20.04+, Debian 11+, Fedora 36+, Arch Linux, or other distros with Node.js 22+
  • Node.js 22+ - Required. The one-line installer can install it for you, or install manually: nodejs.org
  • Terminal access - SSH or local shell
  • LLM API key - At least one: Anthropic Claude, OpenAI, DeepSeek, or Ollama (local)
  • Optional: A messaging app account (e.g. Telegram, Discord, WhatsApp) for your first channel

3. Quick Install (One-Line Installer)

From a terminal on your Linux machine, run:

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

The script will:

  • Detect your Linux distribution
  • Install Node.js 22+ if needed (via package manager or nvm)
  • Download and install OpenClaw
  • Create ~/.openclaw and launch the onboarding wizard

After it finishes, run openclaw setup if the wizard did not start, then enable the systemd service below for production use.

See the Quick Start Guide for full onboarding steps (model provider, API key, first channel).

4. Manual Installation (Optional)

If you prefer not to use the install script, install Node.js 22+ then:

# Clone the repository (use official repo when available)
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm run setup

Or install the CLI via npm (if published):

npm install -g openclaw
openclaw setup

Ensure openclaw is on your PATH. If you get “openclaw command not found”, see Troubleshooting.

5. Distribution-Specific Notes

Ubuntu / Debian

Install Node.js 22+ if not already present (NodeSource or your distro’s repo):

# Example: NodeSource for Node 22 (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Then run the one-line installer above. For headless servers, ensure curl and git are installed: sudo apt-get install -y curl git.

Fedora / RHEL

Install Node.js 22+ (e.g. from NodeSource or dnf if available), then run the install script. Install curl and git if needed: sudo dnf install -y curl git.

Arch Linux

Install Node.js: sudo pacman -S nodejs npm. Ensure you have Node 22+ (node -v). Then run the one-line installer. On Arch, the script should detect your OS and proceed.

6. Run as a systemd Service (Recommended for Servers)

To start OpenClaw on boot and keep it running in the background:

# Install the systemd unit (run from the user that will run OpenClaw)
sudo openclaw service install --systemd

# Enable and start the service
sudo systemctl enable openclaw
sudo systemctl start openclaw

# Check status
sudo systemctl status openclaw
openclaw status

Logs: journalctl -u openclaw -f or openclaw logs. For security on a server, bind the gateway to 127.0.0.1 only and use SSH or a VPN for access; see Security Best Practices and Network Isolation.

7. Verify Installation

After installation and onboarding:

openclaw status
openclaw doctor

openclaw doctor checks configuration, gateway, and common issues. Send a test message from your connected channel (e.g. Telegram) to confirm the agent responds. For more diagnostics, see the Troubleshooting Guide.

8. Common Issues

Issue Solution
openclaw command not found Ensure the install script added the binary to your PATH (e.g. ~/.local/bin or ~/.openclaw/bin). Add to ~/.bashrc or ~/.profile and re-login, or use the full path. See Installation Errors.
Node.js version too old OpenClaw requires Node.js 22+. Run node -v. Install Node 22+ via NodeSource, nvm, or your distro and re-run the installer.
Gateway won't start Check port 1618 is free; ensure gateway binds to 127.0.0.1 on servers. Run openclaw doctor and see Gateway Issues.
Permission denied / EACCES Fix ownership of ~/.openclaw and ensure your user can write to it. Avoid running the CLI as root for normal use.
systemd service fails Check sudo journalctl -u openclaw -n 50. Ensure the user in the unit file has OpenClaw installed and ~/.openclaw is readable. Run openclaw doctor as that user.

For more fixes, see the full Troubleshooting Guide.

9. Best Practices

  • Security: Follow our Security Best Practices. On VPS/servers, bind the gateway to localhost and use network isolation or a VPN.
  • Updates: Regularly update OpenClaw. After upgrading, restart the service: sudo systemctl restart openclaw.
  • Logs: Monitor logs for errors: openclaw logs or journalctl -u openclaw -f.
  • Backups: Back up ~/.openclaw (config and credentials). Keep credentials out of version control.
  • Post-install: Run through the Security Checklist after setup.

10. Next Steps

Related Resources