OpenClaw on Debian: Production-Ready Setup From Scratch

Debian is the distro that doesn't break. Upgrades are conservative, packages are tested, and the platform has been under continuous development since 1993. That makes it a natural home for an AI agent gateway that you want running quietly for months without touching it. The only friction is Node.js — Debian's package maintainers are conservative by design, and the default nodejs version lags behind what OpenClaw requires.

Debian 11 vs Debian 12: What Changes

The setup procedure below works on both versions. The only difference is the NodeSource setup command, which we note at the appropriate step.

Install Node.js via NodeSource

Update your package index and install prerequisites:

sudo apt update
sudo apt install -y curl gnupg ca-certificates

Add the NodeSource repository for Node.js 20 LTS:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

Install Node.js:

sudo apt install -y nodejs

Verify:

node --version   # v20.x.x
npm --version    # v10.x.x

Install OpenClaw

With the correct Node.js in place, install OpenClaw globally:

sudo npm install -g openclaw

Verify the install:

openclaw --version

If this returns "command not found", npm's global bin directory is not in your PATH. Find where npm installs globals and add it:

npm config get prefix   # typically /usr/local
# Add /usr/local/bin to PATH if missing
export PATH="/usr/local/bin:$PATH"

Create a Dedicated System User

Never run OpenClaw as root. Create a system user with no login shell:

sudo useradd --system --no-create-home --shell /bin/false openclaw
sudo mkdir -p /var/lib/openclaw /etc/openclaw
sudo chown openclaw:openclaw /var/lib/openclaw

Initialize the gateway configuration:

sudo -u openclaw openclaw gateway init --config /etc/openclaw/gateway.yaml

Edit the config with your API keys and channel settings:

sudo nano /etc/openclaw/gateway.yaml

Restrict file permissions so only root and the openclaw user can read the token:

sudo chown root:openclaw /etc/openclaw/gateway.yaml
sudo chmod 640 /etc/openclaw/gateway.yaml

Create the Systemd Service

Create the unit file:

sudo nano /etc/systemd/system/openclaw.service

Paste this content:

[Unit]
Description=OpenClaw AI Agent Gateway
Documentation=https://aiagentsguides.com/category/installation-setup/
After=network.target
Wants=network-online.target

[Service]
Type=simple
User=openclaw
Group=openclaw
WorkingDirectory=/var/lib/openclaw
ExecStart=/usr/local/bin/openclaw gateway start --config /etc/openclaw/gateway.yaml
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw
NoNewPrivileges=yes
PrivateTmp=yes

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
sudo systemctl status openclaw

The status should show active (running). If it shows failed, check the logs: journalctl -u openclaw -n 50.

Firewall and Nginx Setup

Install and configure UFW:

sudo apt install -y ufw
sudo ufw allow ssh
sudo ufw allow 8080/tcp
sudo ufw enable

For production use, put Nginx in front of OpenClaw instead of exposing port 8080 directly:

sudo apt install -y nginx certbot python3-certbot-nginx

# Create Nginx config
sudo nano /etc/nginx/sites-available/openclaw

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_cache_bypass $http_upgrade;
    }
}

sudo ln -s /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d your-domain.com

With Nginx in place, remove the direct port 8080 UFW rule — all traffic should go through Nginx on port 443.

Common Mistakes on Debian

• Using Debian's default nodejs on Bullseye — version 12 is years out of support; OpenClaw won't install correctly
• Running as root — the systemd service should always use a dedicated system user
• Wrong binary path in ExecStart — always verify with which openclaw after npm install
• Forgetting daemon-reload after editing the unit file — systemd won't pick up changes until you run systemctl daemon-reload
• Not enabling the service — systemctl start runs it now; systemctl enable makes it start on boot; you need both

Frequently Asked Questions

Why can't I install OpenClaw with the default Debian Node.js package?

Debian's default nodejs package is version 12 on Debian 11 (Bullseye) and version 18 on Debian 12 (Bookworm). OpenClaw requires Node.js 18 or newer. On Debian 11, you must use NodeSource to get a supported version. On Debian 12, the default package works but NodeSource gives you a newer LTS.

How do I create a dedicated system user for OpenClaw on Debian?

Run: sudo useradd --system --no-create-home --shell /bin/false openclaw. This creates a system user with no login shell and no home directory. OpenClaw runs as this user via the systemd service, limiting what a compromised process can access on your system.

Which port does OpenClaw use on Debian and how do I open it in the firewall?

OpenClaw's gateway listens on port 8080 by default. Open it with: sudo ufw allow 8080/tcp. If you're running Nginx as a reverse proxy, keep 8080 closed externally and only open 443. The gateway port is configurable in gateway.yaml under the port key.

How do I check OpenClaw logs on Debian?

If running as a systemd service, use: journalctl -u openclaw -f. For real-time logs, the -f flag follows new entries as they appear. To see the last 100 lines: journalctl -u openclaw -n 100. Logs rotate automatically with systemd's journal management.

Can I run OpenClaw behind Nginx on Debian?

Yes. Install nginx, create a server block that proxies to http://localhost:8080, and use Certbot for HTTPS. This is the recommended production setup — Nginx handles SSL termination and OpenClaw stays on localhost only, reducing its exposure to the network.

Does OpenClaw work on Debian 11 Bullseye?

Yes, but you must install Node.js from NodeSource — Debian 11's default nodejs is version 12 which is too old. Add the NodeSource Node.js 20 repository, install nodejs, then install OpenClaw with npm. The rest of the setup is identical to Debian 12.