OpenClaw on Linux: Setup and Configuration

OpenClaw runs well on Linux, both on desktop workstations and headless servers. If you're comfortable with the terminal and want a local AI agent that you fully control, Linux is a natural home for OpenClaw. This guide covers installation across major distributions, headless server setup, and Linux-specific configuration.

Prerequisites#

OpenClaw requires Node.js 18 or later. Check your current version:

node --version

Installing Node.js on Ubuntu/Debian#

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Installing Node.js on Fedora/RHEL#

sudo dnf install nodejs npm

Installing Node.js on Arch Linux#

sudo pacman -S nodejs npm

Using NVM (Recommended for Version Management)#

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

Installing OpenClaw / DenchClaw#

npx denchclaw

Or for a persistent global install:

npm install -g denchclaw
denchclaw

On first run, this:

1. Initializes the workspace at ~/.openclaw-dench/workspace/
2. Creates a DuckDB database
3. Starts the gateway on port 19001
4. Opens the web interface at localhost:3100 (if a browser is available)

On headless servers, the web UI won't auto-open, but the gateway starts and you can access it via SSH tunnel.

Headless Server Setup#

Running DenchClaw on a Linux server (VPS, home server, Raspberry Pi) without a display is a common and powerful configuration. Here's how to set it up:

Start the Gateway#

openclaw gateway start

Check that it's running:

openclaw gateway status

Access the Web UI via SSH Tunnel#

From your local machine:

ssh -L 3100:localhost:3100 -L 19001:localhost:19001 user@your-server

Then open localhost:3100 in your local browser. The DenchClaw UI loads, but the agent runs on the server.

Run as a systemd Service#

For production-quality persistence, run the gateway as a systemd service:

# Install as a service
openclaw gateway install-service
 
# Check service status
systemctl --user status openclaw-dench
 
# View logs
journalctl --user -u openclaw-dench -f

This starts the gateway on user login and restarts it on crash.

For system-level (non-user) service on a server:

sudo tee /etc/systemd/system/openclaw-dench.service > /dev/null << EOF
[Unit]
Description=OpenClaw DenchClaw Gateway
After=network.target
 
[Service]
Type=simple
User=YOUR_USER
WorkingDirectory=/home/YOUR_USER
ExecStart=/usr/bin/openclaw gateway start --foreground
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target
EOF
 
sudo systemctl daemon-reload
sudo systemctl enable openclaw-dench
sudo systemctl start openclaw-dench

Using tmux for Manual Sessions#

For development or testing on a server:

tmux new-session -d -s openclaw 'openclaw gateway start'

Firewall Configuration#

If you want to access DenchClaw from other devices on your network (or from the internet), configure your firewall:

# UFW (Ubuntu)
sudo ufw allow 3100/tcp
sudo ufw allow 19001/tcp
 
# firewalld (Fedora/RHEL)
sudo firewall-cmd --permanent --add-port=3100/tcp
sudo firewall-cmd --permanent --add-port=19001/tcp
sudo firewall-cmd --reload
 
# iptables
sudo iptables -A INPUT -p tcp --dport 3100 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 19001 -j ACCEPT

Security note: Exposing port 19001 (the API) to the internet without authentication is dangerous. Use SSH tunneling, or put the gateway behind a reverse proxy with auth (nginx, Caddy) for internet-facing deployments.

Browser Agent on Linux#

The browser agent on Linux works with Chromium instead of Chrome (or you can install Chrome directly):

Install Chromium#

# Ubuntu/Debian
sudo apt install chromium-browser
 
# Fedora
sudo dnf install chromium
 
# Arch
sudo pacman -S chromium

Configure the Browser Profile Path#

DenchClaw auto-detects common browser profile paths. If your Chromium profile is in a non-standard location:

plugins:
  - name: browser
    config:
      chromePath: "/usr/bin/chromium-browser"
      profilePath: "/home/USER/.config/chromium/Default"

Note: The browser agent on headless servers requires either a virtual display (Xvfb) or headless Chrome mode:

# Install Xvfb for virtual display
sudo apt install xvfb
 
# Or configure headless mode in DenchClaw config

For most server use cases, browser automation is less critical — the text-based CRM operations work perfectly headless.

Configuring Messaging Channels on Linux#

Messaging channels work identically on Linux. The most popular for server deployments:

Telegram#

plugins:
  - name: telegram
    config:
      token: "YOUR_BOT_TOKEN"

Restart: openclaw gateway restart

Discord#

plugins:
  - name: discord
    config:
      token: "YOUR_BOT_TOKEN"
      guildId: "YOUR_SERVER_ID"

See openclaw-discord-bot for full Discord setup.

Webhook Endpoint#

For Linux server deployments, you can expose a webhook that other services call:

plugins:
  - name: webhook
    config:
      path: "/webhook/openclaw"
      secret: "YOUR_WEBHOOK_SECRET"

Linux-Specific Performance Notes#

File system: DuckDB performs best on ext4 or APFS. Avoid running the workspace on NFS mounts or FUSE filesystems.

Memory: Minimum 512MB free RAM for the gateway. 2GB+ recommended if you're also running local AI models via Ollama.

CPU: DenchClaw's core CRM operations are I/O-bound, not CPU-bound. Even a Raspberry Pi 4 handles the database and agent routing well. Local AI inference is where CPU matters — use API-based models on lower-powered hardware.

Ollama for Local AI on Linux: Linux is the best platform for running Ollama with GPU acceleration:

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh
 
# Pull a model
ollama pull llama3.2
 
# Configure DenchClaw to use it

With an NVIDIA GPU, Ollama on Linux delivers significantly better inference performance than macOS.

Updating OpenClaw#

npm update -g denchclaw
openclaw gateway restart

Your workspace data at ~/.openclaw-dench/workspace/ is preserved through updates.

Troubleshooting on Linux#

Permission denied on port 19001: Ports below 1024 require root. Port 19001 doesn't — this error usually means another process is using the port:

lsof -ti :19001 | xargs kill -9

Gateway fails to start after system update:

rm -rf ~/.openclaw-dench/.gateway
openclaw gateway start

Telegram bot not responding: Check that your server can reach the Telegram API — some VPS providers block outbound connections:

curl https://api.telegram.org

DuckDB file locked: If you're running multiple OpenClaw instances pointing at the same workspace:

fuser ~/.openclaw-dench/workspace/workspace.duckdb

Frequently Asked Questions#

Does OpenClaw work on Raspberry Pi?#

Yes. Raspberry Pi 4 (4GB+ RAM recommended) runs the core gateway and CRM operations well. Use API-based AI models (not local inference) and disable the browser agent for best performance.

Can I run OpenClaw in a Docker container?#

Yes, though it's not the primary supported deployment model. The main consideration is that the browser agent needs access to a Chrome/Chromium installation. For CRM-only use without browser automation, a minimal Docker container works well.

How do I access DenchClaw from my phone when the server is on my home network?#

Either: (1) Set up a VPN to your home network (WireGuard is popular), or (2) Use a messaging channel like Telegram that works anywhere. Option 2 is simpler for most people.

Is there a difference between OpenClaw on Linux vs Mac?#

Minor differences: the browser profile auto-detection path differs, and some macOS-specific skills (Apple Notes, iMessage, Things 3) don't work on Linux. Core CRM, browser automation, and messaging channels work identically.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →