Installing OpenClaw on Linux

Prerequisites

OpenClaw requires Python 3.10 or later. Check your version:

python3 --version
# Python 3.10.12 or newer

Ubuntu / Debian

sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip

Ubuntu 22.04+ (Python 3.11)

sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-pip

Fedora / RHEL / CentOS

sudo dnf install python3 python3-pip

Arch Linux

sudo pacman -S python python-pip

Recommended: Virtual Environment Install

Using a virtual environment isolates OpenClaw from your system Python packages:

# Create a virtual environment
python3 -m venv ~/.venvs/openclaw

# Activate it
source ~/.venvs/openclaw/bin/activate

# Install OpenClaw
pip install openclaw

# Verify
openclaw --version

Add activation to your shell profile for convenience:

# Add to ~/.bashrc or ~/.zshrc
echo 'alias openclaw-activate="source ~/.venvs/openclaw/bin/activate"' >> ~/.bashrc
echo 'source ~/.venvs/openclaw/bin/activate' >> ~/.bashrc
source ~/.bashrc

System-Wide Install (pip --user)

# Install for current user only (no sudo needed)
pip install --user openclaw

# Add ~/.local/bin to PATH if not already there
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

openclaw --version

⚠️

Ubuntu 22.04+ Note

On Ubuntu 22.04+, direct pip installs may show "externally-managed-environment" error. Use a virtual environment (recommended) or add --break-system-packages flag to pip.

Post-Install Verification

openclaw --version
openclaw --help

# Configure your API key and test
openclaw config set openai.api_key "sk-proj-..."
openclaw run "Hello, can you hear me?"

Shell Completion

# Bash
openclaw completion bash >> ~/.bashrc

# Zsh
openclaw completion zsh >> ~/.zshrc

# Fish
openclaw completion fish > ~/.config/fish/completions/openclaw.fish

source ~/.bashrc  # or restart your terminal

Autostart with systemd

Run OpenClaw as an always-on user service:

mkdir -p ~/.config/systemd/user/
cat > ~/.config/systemd/user/openclaw.service <<'EOF'
[Unit]
Description=OpenClaw AI Agent Service
After=network.target

[Service]
Type=simple
ExecStart=/home/YOUR_USER/.venvs/openclaw/bin/openclaw start --daemon --port 8080
Restart=on-failure
RestartSec=5
Environment=OPENCLAW_PROVIDER=openai
EnvironmentFile=%h/.openclaw/.env

[Install]
WantedBy=default.target
EOF

systemctl --user enable openclaw
systemctl --user start openclaw
systemctl --user status openclaw

💡

See Also

Server Installation — deploy on a VPS or cloud VM
API Keys Setup
Installation Troubleshooting

Verify Your Installation

After installation, run these commands to confirm everything is working:

# Check version
openclaw --version
# OpenClaw v1.x.x

# Check configuration
openclaw config show

# Quick health check
openclaw run "Say 'installation successful' in one short sentence"

First Real Task

# Configure your API key
openclaw config set openai.api_key "sk-proj-..."
openclaw config set provider openai
openclaw config set openai.model gpt-4o-mini

# Run a useful task
openclaw run "Summarise what pip install does in 2 sentences"

# Test with local Ollama model (no API key needed)
# ollama pull llama3.2
# openclaw config set provider ollama
# openclaw config set model llama3.2
# openclaw run "Hello, test"

Update & Uninstall

Upgrade to the Latest Version

# With venv active
pip install --upgrade openclaw
openclaw --version

# System-wide (if installed with --user)
pip install --user --upgrade openclaw

Uninstall

pip uninstall openclaw -y

# Remove config and cache (optional)
rm -rf ~/.openclaw/

Update via apt (if installed from package)

sudo apt update && sudo apt upgrade openclaw

Distribution-Specific Instructions

Distribution	Package Manager	Install Python 3.10+
Ubuntu 22.04+, Debian 12+	apt	`sudo apt install python3 python3-pip python3-venv`
Fedora 38+	dnf	`sudo dnf install python3 python3-pip`
RHEL/CentOS/Rocky 9	dnf	`sudo dnf install python3.11`
Arch Linux / Manjaro	pacman	`sudo pacman -S python python-pip`
openSUSE Tumbleweed	zypper	`sudo zypper install python3 python3-pip`
Alpine Linux	apk	`apk add python3 py3-pip`

Linux Troubleshooting

Error	Cause	Fix
`externally-managed-environment`	Protected system Python (Ubuntu 23.04+)	Use venv: `python3 -m venv ~/.venv/openclaw`
`command not found: openclaw`	venv not activated or PATH issue	Run `source ~/.venv/openclaw/bin/activate`
`error: invalid command 'bdist_wheel'`	Missing build tools	`pip install wheel setuptools --upgrade`
`Permission denied: /usr/local/lib`	Running pip as root without sudo	Use `pip install --user openclaw` or a venv

Running as a systemd Service

To keep an OpenClaw API server or automation daemon running 24/7:

# /etc/systemd/system/openclaw.service
[Unit]
Description=OpenClaw AI Agent Service
After=network.target

[Service]
Type=simple
User=openclaw
WorkingDirectory=/home/openclaw
ExecStart=/home/openclaw/.venv/openclaw/bin/openclaw start --daemon
Restart=on-failure
RestartSec=10
EnvironmentFile=/home/openclaw/.openclaw.env
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw   # verify running

← Installation macOS Installation →