OpenClaw VPS Deployment Errors: Fix Every Common Server Setup Issue

Running openclaw doctor --deep --yes resolves roughly 80% of VPS deployment errors without you touching a config file. If you have not tried that yet, run it now and come back to this guide for whatever remains.

The errors below are the ones that come up repeatedly in the OpenClaw community, from 2GB Hostinger boxes to dedicated 32GB machines running multi-channel agents. They are organized by the exact message you will find in your terminal or logs. Each section starts with the error, explains why it happens, and gives you the fix.

If you have not deployed yet and want the smoothest path, start with our Hostinger one-click setup guide. This guide assumes OpenClaw is already on the server and something went wrong.

---

Run the Diagnostic First

Before chasing individual errors, run a single diagnostic pass that checks Node.js version, port availability, memory, systemd status, and firewall rules:

openclaw doctor --deep --yes

This command auto-detects and fixes configuration drift, stale PID files, missing environment variables, and version mismatches. If it reports all green, your issue is likely network-level (SSL, firewall, or DNS). If it flags something, follow its remediation steps before continuing.

For headless VPS environments where the TUI installer stalls because there is no TTY, use:

openclaw doctor --non-interactive

This skips the interactive prompts and writes a default config. Most cheap VPS providers drop you into a headless shell, and the standard installer hangs silently. If your install seemed to freeze during the initial curl | bash setup, this is almost certainly why.

---

EADDRINUSE: Port 18789 Already in Use

What you see:

Error: listen EADDRINUSE: address already in use :::18789

Why it happens: Another process is holding port 18789, which is OpenClaw’s default gateway port. This typically occurs after a crash left an orphan process, or you are running a second OpenClaw instance.

Fix:

Find and kill the process occupying the port:

lsof -i :18789
kill -9 <PID>

Then restart OpenClaw. If this keeps happening after crashes, your systemd unit file is probably missing Restart=always and RestartSec=2, which means the old process is not cleaned up before the new one starts. Add these to your service file:

[Service]
Restart=always
RestartSec=2
TimeoutStartSec=90

Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart openclaw

---

npm Install Failures and Dependency Errors

What you see: Errors during npm install or pnpm install referencing missing native modules, node-gyp compilation failures, or unresolved peer dependencies.

Why it happens: The VPS is missing build tools required for native Node.js module compilation. Minimal Ubuntu images (which most VPS providers ship by default) do not include build-essential, python3, or gcc.

Fix:

Install the build toolchain first:

sudo apt update
sudo apt install -y build-essential python3 gcc g++ make

Then retry the install. If you are on a 1GB RAM VPS and the install itself crashes (the compiler runs out of memory), add temporary swap:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

After the install completes, you can remove the swap or keep it as a safety net. Keeping at least 1GB of swap on any VPS running OpenClaw is recommended.

---

Node.js Version Mismatch

What you see: Obscure syntax errors during startup, SyntaxError: Unexpected token, or dependency install failures that do not point to the Node version as the cause.

Why it happens: OpenClaw requires Node.js 20 LTS or newer. Many VPS images ship with Node 16 or 18 pre-installed, and the errors you get from running OpenClaw on an older version are misleading. They look like code bugs, not version problems.

Fix:

Check your current version:

node --version

If it reports anything below v20, install the correct version using nvm:

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

Node 22 is recommended over Node 20 because OpenClaw’s dependency tree resolves more cleanly on 22, and you avoid edge cases with native module compilation that still surface on 20.x point releases.

After switching versions, delete node_modules and reinstall:

rm -rf node_modules
npm install

---

Memory Crashes and OOM Kills

What you see: OpenClaw stops responding, journalctl shows oom-kill entries, or the process silently disappears from ps aux.

Why it happens: Each active OpenClaw conversation consumes roughly 512MB to 1GB of RAM depending on context window size. A 2GB VPS handling two simultaneous conversations plus the operating system overhead will exhaust memory and trigger the kernel OOM killer.

Fix:

First, check current memory pressure:

free -h

Then size your VPS appropriately:

VPS RAM	Max Concurrent Conversations	Swap Recommendation
2GB	1	2GB swap mandatory
4GB	2-3	1GB swap recommended
8GB	5-7	Optional
16GB+	10+	Not needed

If you cannot upgrade the VPS, reduce context window size in your OpenClaw config and add swap as described in the npm install section above. Also set a memory limit in your systemd unit:

[Service]
MemoryMax=3G
MemoryHigh=2.5G

This prevents the OOM killer from taking down other services on the same machine. OpenClaw will restart cleanly via Restart=always instead of the kernel killing it unpredictably. For persistent performance issues beyond memory, see our OpenClaw high CPU usage guide.

---

systemd Service Failures

What you see: systemctl status openclaw shows failed, inactive (dead), or activating stuck in a loop.

Why it happens: The systemd unit file has incorrect paths, missing environment variables, or the service is trying to start before the network is ready.

Fix:

Check the logs first:

journalctl -u openclaw -n 50 --no-pager

The most common causes:

1. Missing environment variables. Your API keys are not in the systemd environment. Add them to the unit file:

[Service]
Environment="OPENAI_API_KEY=sk-..."
Environment="ANTHROPIC_API_KEY=sk-ant-..."

Or use an environment file:

[Service]
EnvironmentFile=/home/openclaw/.env

2. Wrong working directory. The WorkingDirectory in the unit file does not point to where OpenClaw is installed:

[Service]
WorkingDirectory=/home/openclaw/openclaw

3. Stale PID file. A previous crash left /home/openclaw/.openclaw/gateway.pid with a dead PID. Remove it:

rm ~/.openclaw/gateway.pid
sudo systemctl restart openclaw

4. Network not ready. Add After=network-online.target to your unit:

[Unit]
After=network-online.target
Wants=network-online.target

---

Firewall Blocking Connections

What you see: OpenClaw starts fine but Telegram, WhatsApp, or other channels cannot reach it. External requests time out. curl localhost:18789 works from the server but curl your-server-ip:18789 fails from your laptop.

Why it happens: UFW (or iptables) is blocking inbound traffic on the ports OpenClaw needs. Many VPS setup guides tell you to enable the firewall but forget to open the application ports.

Fix:

If you are using Nginx as a reverse proxy (which you should be), you only need ports 80, 443, and SSH:

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

Do not open port 18789 to the public internet. The gateway should bind to 127.0.0.1 (localhost only) and Nginx should proxy requests to it. If openclaw gateway status shows the gateway listening on 0.0.0.0:18789, fix that immediately:

openclaw configure

Set the bind address to 127.0.0.1. Exposing the raw gateway port means anyone on the internet can hit your OpenClaw API directly, with your API keys.

---

SSL and Nginx Proxy Errors

What you see: 502 Bad Gateway from Nginx, or ERR_SSL_PROTOCOL_ERROR in the browser, or WebSocket connections dropping every few minutes.

Why it happens: Three distinct issues get lumped under “SSL errors”:

1. 502 Bad Gateway: Nginx is running but OpenClaw’s gateway process is not. Nginx proxies to localhost:18789, gets no response, and returns 502.

2. SSL certificate issues: Certbot failed to issue or renew the certificate, usually because port 80 is blocked by the firewall or another service is occupying it.

3. WebSocket disconnections: Nginx’s default proxy_read_timeout is 60 seconds, which kills idle WebSocket connections. OpenClaw’s gateway uses long-lived WebSocket connections that can idle for minutes.

Fix for 502:

openclaw gateway status
sudo systemctl status openclaw

If the gateway is down, restart it. If it keeps dying, check the systemd and memory sections above.

Fix for SSL:

sudo certbot renew --dry-run

If renewal fails, ensure ports 80 and 443 are open in UFW and no other service (like Apache) is binding to port 80.

Fix for WebSocket drops:

Add these lines to your Nginx server block:

location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 86400;
}

The proxy_read_timeout 86400 value (24 hours) prevents Nginx from killing idle connections. The Upgrade and Connection headers are required for WebSocket passthrough.

---

API Key Authentication Errors (401 Unauthorized)

What you see: 401 Unauthorized when OpenClaw tries to call your LLM provider, or Error: All models failed in the logs.

Why it happens: The API key is missing, has extra whitespace from copy-paste, references the wrong environment variable name, or the key has no credits loaded on the provider’s side.

Fix:

Test your API key directly:

openclaw models test

If that fails, check the key manually:

echo $OPENAI_API_KEY | cat -A

The cat -A flag shows invisible characters. If you see $ at the end (normal) but also ^M or spaces, the key has hidden characters. Re-set it cleanly:

export OPENAI_API_KEY="sk-your-key-here"

For systemd deployments, ensure the environment file does not have trailing spaces or Windows-style line endings. Convert if needed:

sed -i 's/\r$//' /home/openclaw/.env

Also verify the key actually has credits. A valid API key with zero balance returns 401 on most providers, not a “no credits” error. Log into your provider dashboard and check.

---

Frequently Asked Questions

Why won’t OpenClaw start on my VPS?

Run openclaw doctor --deep --yes first. It catches the majority of startup issues automatically. If it passes but OpenClaw still will not start, check journalctl -u openclaw -n 50 for the specific error message and find it in the sections above. The three most common causes are a stale PID file, missing environment variables in the systemd unit, and Node.js version below 20.

How much RAM does OpenClaw need on a VPS?

Plan for 512MB to 1GB per concurrent conversation on top of base system usage. A 4GB VPS comfortably handles 2-3 simultaneous conversations. If you are running a single-user agent that handles one conversation at a time, 2GB with swap is sufficient. A 4GB VPS is the sweet spot for most deployments.

How do I check OpenClaw logs for errors?

Stream logs in real time with JSON filtering:

openclaw logs --follow --json | jq 'select(.level == "error")'

For systemd-managed installations, use:

journalctl -u openclaw -f

What does openclaw doctor do?

It runs a diagnostic scan checking Node.js version, port availability, configuration validity, API key presence, gateway connectivity, and file permissions. With --deep, it also verifies skill directories and memory persistence. With --yes, it auto-applies fixes instead of just reporting them. On headless servers, add --non-interactive to skip the TUI prompts.

How do I fix OpenClaw WebSocket Error 4008?

Error 4008 means the gateway WebSocket connection failed. Check that your GATEWAY_URL uses the correct protocol: wss:// for HTTPS deployments, ws:// for local-only setups. If you are behind Nginx, verify the proxy configuration includes the Upgrade and Connection headers for WebSocket passthrough. See the SSL and Nginx section above for the exact config.

Why does OpenClaw forget everything after a restart?

OpenClaw stores conversation state in memory by default. On a VPS, you need to enable persistent storage. If you are running via Docker, mount the data volume explicitly. For direct installs, verify the data directory path with openclaw config get storage.directory and confirm the systemd user has write permissions to that path. For a deeper dive into persistence configuration, see our OpenClaw memory not persisting guide.

Can I run OpenClaw alongside other services on the same VPS?

Yes, but size your RAM accordingly. OpenClaw plus Nginx plus the OS typically uses 1-1.5GB at idle. Every active conversation adds 512MB-1GB on top. If you are also running a database or web application on the same machine, monitor memory with htop and set MemoryMax in the systemd unit to prevent OpenClaw from starving your other services.

---

Key Takeaways

• Run openclaw doctor --deep --yes before doing anything else. It resolves the majority of deployment errors automatically.
• Most VPS deployment failures are environment issues, not OpenClaw bugs: wrong Node version, missing build tools, insufficient RAM, or misconfigured firewalls.
• Size your VPS at 4GB minimum for production use. Budget 512MB-1GB per concurrent conversation.
• Never expose port 18789 directly. Always proxy through Nginx with WebSocket headers and a 24-hour read timeout.
• If you followed our Hostinger setup guide and hit problems, this guide covers the most common errors from that deployment path.