Self-Host OpenClaw on Any Linux Server

This guide covers installing OpenClaw Gateway on any Ubuntu or Debian-based Linux server, whether it is a bare-metal machine, a VPS from any provider, or a homelab box under your desk. Two installation paths are documented: a direct install using the official installer script, and a Docker-based setup for those who prefer container isolation.

Quick path

Direct install in five commands:

1. curl -fsSL https://openclaw.ai/install.sh | bash
2. openclaw doctor (verify environment)
3. openclaw setup (configure gateway token, bind, port)
4. Copy the systemd unit below, run systemctl enable --now openclaw-gateway
5. SSH tunnel from your machine: ssh -N -L 18789:127.0.0.1:18789 user@SERVER_IP

Prerequisites

• Ubuntu 22.04+ or Debian 11+ (other distributions may work but are untested)
• At least 2 GB RAM (1 GB with swap as a minimum)
• 10 GB free disk space
• SSH access to the server
• A non-root user with sudo privileges (or root access)

Path A — Direct Install (Recommended)

The direct install is the fastest way to get OpenClaw running. It installs Node.js if needed, downloads the OpenClaw binary, and sets up the configuration directory.

Step 1 — Run the installer

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

The script will:

• Detect your OS and architecture
• Install Node.js 24 if not present or if the installed version is too old
• Download and install the OpenClaw Gateway binary to /usr/local/bin/
• Create the configuration directory at ~/.openclaw
• Create the workspace directory at ~/.openclaw/workspace

Step 2 — Verify the installation

openclaw --version

This should print the installed version. If you get command not found, see the Troubleshooting section below.

Run the environment checker:

openclaw doctor

The doctor command validates:

• Node.js version (24+ required)
• Available memory and swap
• Disk space
• Network connectivity
• Write permissions on the configuration directory

Fix any issues it reports before proceeding.

Step 3 — Configure the gateway

Run the interactive setup wizard:

openclaw setup

You will be prompted for:

• Gateway token: A secret used to authenticate clients. Let the wizard generate one, or provide your own (at least 32 characters).
• Bind address: loopback (127.0.0.1, most secure) or lan (all interfaces, useful for Tailscale).
• Port: Default 18789.
• Workspace path: Default ~/.openclaw/workspace.

The configuration is saved to ~/.openclaw/config.toml:

[gateway]
token = "your_token_here"
bind = "loopback"
port = 18789

[workspace]
path = "/home/youruser/.openclaw/workspace"

You can edit this file directly at any time. Restart the service after changes.

Step 4 — Test the gateway

Start the gateway manually to confirm everything works:

openclaw gateway start

You should see output indicating the gateway is listening. Press Ctrl+C to stop it once confirmed.

Step 5 — Create a systemd service

Set up systemd so the gateway runs on boot and restarts on failure:

sudo cat > /etc/systemd/system/openclaw-gateway.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/.openclaw
ExecStart=/usr/local/bin/openclaw gateway start
Restart=on-failure
RestartSec=5
Environment=NODE_ENV=production

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/youruser/.openclaw

[Install]
WantedBy=multi-user.target
EOF

Replace youruser with your actual username.

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway

Verify:

sudo systemctl status openclaw-gateway
sudo journalctl -u openclaw-gateway -f --no-pager -n 30

Path B — Docker Install

If you prefer containerized deployments, this path uses Docker Compose.

Step 1 — Install Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect.

docker --version
docker compose version

Step 2 — Create directory structure

mkdir -p ~/.openclaw/workspace

Step 3 — Create the environment file

cat > ~/.openclaw/.env << 'EOF'
OPENCLAW_GATEWAY_TOKEN=your_token_here
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_GATEWAY_PORT=18789
GOG_KEYRING_PASSWORD=your_keyring_password_here
EOF
chmod 600 ~/.openclaw/.env

Generate secure values for the token and keyring password:

openssl rand -hex 32  # Use for OPENCLAW_GATEWAY_TOKEN
openssl rand -hex 32  # Use for GOG_KEYRING_PASSWORD

Step 4 — Write the Docker Compose file

# ~/.openclaw/docker-compose.yml
services:
  openclaw-gateway:
    image: ghcr.io/openclaw/gateway:latest
    container_name: openclaw-gateway
    restart: unless-stopped
    env_file:
      - .env
    ports:
      - "127.0.0.1:18789:18789"
    volumes:
      - ./:/home/openclaw/.openclaw
      - ./workspace:/home/openclaw/workspace
    security_opt:
      - no-new-privileges:true
    read_only: true
    tmpfs:
      - /tmp

Step 5 — Start the container

cd ~/.openclaw
docker compose up -d
docker compose ps
docker compose logs --tail 30

Connecting to the Gateway

SSH tunnel

On your local machine, forward the gateway port through SSH:

ssh -N -L 18789:127.0.0.1:18789 user@SERVER_IP

Then open http://127.0.0.1:18789/ in your browser.

Add this to your local ~/.ssh/config for convenience:

Host openclaw-server
    HostName SERVER_IP
    User youruser
    LocalForward 18789 127.0.0.1:18789
    ServerAliveInterval 60
    ServerAliveCountMax 3

Then just run ssh -N openclaw-server.

Tailscale (alternative)

If your server is on a Tailscale network, you can access OpenClaw without SSH tunnels:

# On the server
curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
tailscale serve --bg https+insecure://127.0.0.1:18789

Access via https://SERVER_TAILSCALE_NAME:443/ from any device on your tailnet.

Firewall Configuration

Using ufw (Ubuntu/Debian)

sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp comment "SSH"
sudo ufw enable
sudo ufw status verbose

Do not open port 18789 in the firewall. Access is through SSH tunnel or VPN only.

Using iptables directly

If you prefer raw iptables:

sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT
sudo iptables -A INPUT -i lo -j ACCEPT
sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
sudo iptables -A INPUT -j DROP

# Persist the rules
sudo apt install iptables-persistent -y
sudo netfilter-persistent save

Security Best Practices

Keep OpenClaw off the public internet

OpenClaw Gateway executes code on your server. Never bind it to 0.0.0.0 without a VPN or tunnel in front. The 127.0.0.1 binding in the Docker Compose file and the loopback setting in config.toml enforce this.

Automatic security updates

sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure -plow unattended-upgrades

SSH hardening

Disable password authentication:

sudo sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo sed -i 's/PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

Run as a dedicated user

Avoid running OpenClaw as root. Create a dedicated system user:

sudo adduser --system --home /home/openclaw --shell /bin/bash --group openclaw
sudo mkdir -p /home/openclaw/.openclaw/workspace
sudo chown -R openclaw:openclaw /home/openclaw

Update the systemd unit or Docker user mapping accordingly.

Swap Setup for Low-Memory Servers

If your server has 1-2 GB of RAM, add swap to prevent OOM kills:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Verify with free -h.

Troubleshooting

openclaw: command not found

The installer places the binary in /usr/local/bin/. If this is not in your PATH:

# Check where it was installed
which openclaw || find / -name openclaw -type f 2>/dev/null

# Add to PATH if needed
export PATH="/usr/local/bin:$PATH"
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

If running under systemd, ensure the ExecStart uses the full path (/usr/local/bin/openclaw).

npm sharp build errors

The sharp image processing library requires native dependencies. If you see build errors during installation:

sudo apt install -y build-essential libvips-dev

Then re-run the installer:

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

Node.js version too old

The installer should handle this, but if you have a system-managed Node.js that takes precedence:

# Remove the old version
sudo apt remove -y nodejs

# Install Node.js 24 from NodeSource
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash -
sudo apt install -y nodejs

# Verify
node --version

Gateway fails to start — EADDRINUSE

Port 18789 is already in use:

sudo ss -tlnp | grep 18789

Either stop the conflicting process or change the port in config.toml / .env.

Systemd service keeps restarting

Check the logs for the root cause:

sudo journalctl -u openclaw-gateway -e --no-pager -n 100

Common causes:

• Missing or corrupt config.toml
• Insufficient memory (check dmesg | grep -i oom)
• Wrong file permissions — the service user must own ~/.openclaw

Docker container exits immediately

docker compose logs openclaw-gateway

Common causes:

• Missing .env file or wrong path in env_file
• Volume mount permissions — ensure the host directories exist and are writable
• Insufficient disk space — check with df -h

Connection refused on localhost

1. Confirm the service is running: systemctl is-active openclaw-gateway or docker compose ps
2. Confirm the port is listening: ss -tln | grep 18789
3. Confirm you are connecting to 127.0.0.1, not the server's public IP
4. If using SSH tunnel, verify the tunnel is active with ssh -v

Updating OpenClaw

Direct install

curl -fsSL https://openclaw.ai/install.sh | bash
sudo systemctl restart openclaw-gateway
openclaw --version

Docker

cd ~/.openclaw
docker compose pull
docker compose up -d
docker compose logs --tail 10

Your configuration and workspace data are preserved in both cases, since they live on the host filesystem.

Next Steps

• Set up automated backups of ~/.openclaw using restic, borgbackup, or provider-specific snapshots
• Configure log rotation for systemd journal output: sudo journalctl --vacuum-size=500M
• Explore running multiple OpenClaw instances for different projects on separate ports
• Add monitoring with a lightweight tool like Netdata or Prometheus Node Exporter