OpenClaw Docker Setup: Common Problems & How to Skip Docker Entirely

OpenClaw's official docs point you toward Docker. Makes sense — it's a clean, reproducible install. Clone the repo, run docker compose up, and your AI agent should be live.

Except when it isn't.

If you're here, you probably ran into one of the many Docker issues that the OpenClaw docs don't adequately cover. Port conflicts. Permission errors. Containers eating all your RAM. Upgrades that nuke your conversation history.

This guide covers the six most common OpenClaw Docker problems, gives you actual fixes, and then offers an honest alternative if you're tired of fighting with containers.

Problem #1: Port Conflicts

What Happens

You run docker compose up and get:

Error response from daemon: driver failed programming external connectivity:
Bind for 0.0.0.0:3000 failed: port is already allocated

Something else on your server is already using port 3000. On a fresh VPS this is usually Grafana, a Node.js dev server, or another Docker container you forgot about.

The Fix

Find what's using the port:

sudo lsof -i :3000

Then either stop that service or change OpenClaw's port. In your docker-compose.yml, update the port mapping:

ports:
  - "3001:3000"

This maps your host's port 3001 to OpenClaw's internal port 3000. If you're running OpenClaw purely as a chat agent (Discord/Telegram/Slack), you may not need the web port exposed at all — you can remove the ports section entirely. For more on running OpenClaw across multiple platforms, see our complete OpenClaw guide.

Problem #2: Volume Mount Permission Errors

What Happens

OpenClaw starts but can't write to its data directory:

EACCES: permission denied, open '/app/data/openclaw.db'

Or worse, it starts fine but silently fails to persist data. You restart the container and all conversation history is gone.

The Fix

Docker containers run as a specific user (often root inside the container, but mapped to a different UID on the host). The directory you're mounting needs to be writable by that user.

# Check the UID OpenClaw runs as inside the container
docker exec openclaw id

# Set ownership on your host data directory
sudo chown -R 1000:1000 ./data

# Or use the more permissive approach (less secure)
chmod -R 777 ./data

The better long-term fix is to set the user explicitly in docker-compose.yml:

services:
  openclaw:
    user: "${UID}:${GID}"
    volumes:
      - ./data:/app/data

Then export your host user's UID/GID before running compose:

export UID=$(id -u) GID=$(id -g)
docker compose up -d

Problem #3: KVM / Virtualization Requirements

What Happens

You're running a cheap VPS and Docker won't start at all:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Or Docker starts but containers crash with kernel-related errors.

The Fix

Some budget VPS providers (especially OpenVZ-based ones) don't support Docker at all. Docker requires a modern Linux kernel with cgroup v2 support. Older virtualization technologies like OpenVZ can't provide this.

Check your virtualization type:

systemd-detect-virt

If it says openvz or lxc, Docker will not work reliably. You need a KVM-based VPS. Hetzner, DigitalOcean, Linode, and Vultr all use KVM. Some of the ultra-cheap providers (BuyVM on certain plans, some OVH offerings) use OpenVZ — avoid these if you need Docker.

If you're stuck on an incompatible VPS, your options are:

1. Migrate to a KVM provider
2. Run OpenClaw without Docker (bare metal Node.js install)
3. Use managed hosting that handles the infrastructure for you

Problem #4: Memory Issues and OOM Kills

What Happens

OpenClaw runs fine for a few hours or days, then suddenly stops. You check and the container was killed:

docker inspect openclaw | grep -i oom
# "OOMKilled": true

Your server ran out of memory and the Linux kernel killed the biggest offender — your OpenClaw container.

The Fix

OpenClaw with an active conversation context can use 500MB–1.5GB of RAM depending on your configuration. If you're running on a 1GB VPS, you're going to have a bad time.

Minimum recommendation: 2GB RAM for OpenClaw via Docker. Docker itself has overhead (~100–200MB), plus the OS needs room to breathe.

Add a memory limit to prevent uncontrolled growth:

services:
  openclaw:
    deploy:
      resources:
        limits:
          memory: 1.5G

Also add swap space if you haven't:

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

Swap is slower than RAM but prevents OOM kills. Your bot might respond a bit slower under memory pressure, but it won't die.

Problem #5: Upgrade Crashes and Data Loss

What Happens

OpenClaw releases a new version. You pull the latest image and restart:

docker compose pull
docker compose up -d

And one of these things happens:

• The container won't start due to breaking config changes
• Your conversation database is incompatible with the new version
• Environment variables were renamed and your .env file is now wrong
• The new version needs a different Node.js version than what's baked into the image

The Fix

Always back up before upgrading:

# Stop the container
docker compose down

# Back up your data and config
cp -r ./data ./data.backup.$(date +%Y%m%d)
cp .env .env.backup.$(date +%Y%m%d)

# Pull and restart
docker compose pull
docker compose up -d

# Check logs immediately
docker compose logs -f --tail=50

Pin your image version instead of using latest:

services:
  openclaw:
    image: openclaw/openclaw:v3.2.1  # pin to specific version

This way upgrades only happen when you explicitly change the version number. You can review the changelog first and upgrade on your schedule.

If an upgrade breaks things, roll back:

docker compose down
cp -r ./data.backup.20260322 ./data
# Change image tag back to previous version in docker-compose.yml
docker compose up -d

Problem #6: Networking and Platform Connection Issues

What Happens

OpenClaw starts, logs look clean, but your Discord/Telegram/Slack bot doesn't respond to messages. Or it works for a while and then stops.

The Fix

This is usually one of three things:

DNS resolution inside Docker:

# Test DNS from inside the container
docker exec openclaw nslookup api.telegram.org

If DNS fails, add explicit DNS servers to your compose file:

services:
  openclaw:
    dns:
      - 8.8.8.8
      - 1.1.1.1

WebSocket connections timing out: Some Docker network configurations interfere with the persistent WebSocket connections that Discord and Slack use. If your bot connects then disconnects repeatedly, try switching to host networking:

services:
  openclaw:
    network_mode: host

This bypasses Docker's network layer entirely. Less isolated, but eliminates network-related issues.

Firewall blocking outbound traffic: If you're running ufw on the host, Docker's iptables rules can conflict with it. The classic symptom is that everything works with ufw disabled but breaks when you enable it. The fix is ugly but well-documented — search for "Docker UFW conflict" for your specific setup.

---

Or Skip Docker Entirely

Every problem above has a fix. But they all share a common theme: you're spending time maintaining infrastructure instead of using your AI agent.

Docker adds a layer of abstraction that's valuable for complex deployments but overkill for running a single application on a single server. The abstraction creates problems that wouldn't exist if you just ran OpenClaw directly.

You have two alternatives to Docker:

Option 1: Bare Metal Install

Skip Docker and install OpenClaw directly on your VPS:

# Install Node.js 20+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
sudo apt install -y nodejs

# Clone and install OpenClaw
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install

# Configure and run
cp .env.example .env
# Edit .env with your API keys and platform tokens
npm start

Use PM2 to keep it running:

npm install -g pm2
pm2 start npm --name openclaw -- start
pm2 startup
pm2 save

This eliminates every Docker-specific problem above. No port mapping issues, no volume permission problems, no virtualization requirements, no Docker memory overhead, no image versioning headaches, no networking layer conflicts.

The trade-off: you're managing Node.js versions and system dependencies yourself. But for a single application, that's simpler than managing Docker.

Option 2: Managed Hosting

If you don't want to manage infrastructure at all — no Docker, no VPS, no SSH — managed hosting handles everything.

ClawdHost runs OpenClaw on dedicated Hetzner VPS instances (not shared containers). You provide your API key (all plans are BYOK — bring your own key), connect your platform tokens, and your agent is live in about 60 seconds.

No Docker. No Linux. No troubleshooting at 3am.

It costs $29/month and includes 4-platform support (Discord, Telegram, WhatsApp, Slack), automatic updates, crash recovery, and AES-256 encryption for your credentials. See how it stacks up against other providers in our OpenClaw hosting alternatives comparison.

---

Docker vs Bare Metal vs Managed: The Comparison

	Docker (Self-Host)	Bare Metal (Self-Host)	Managed (ClawdHost)
Monthly cost	$4–18 (VPS)	$4–18 (VPS)	$29/mo
Setup time	30–90 min	15–45 min	~60 seconds
Docker required	Yes	No	No
KVM VPS required	Yes	No (any VPS works)	N/A
Memory overhead	~200MB Docker overhead	None	N/A
Upgrade process	Pull image, pray	Git pull, restart	Automatic
Crash recovery	Manual or custom config	PM2 auto-restart	Automatic + alerts
Port conflicts	Common issue	Not an issue	N/A
Permission errors	Common issue	Rare	N/A
Linux knowledge	Required	Required	Not needed
Multi-platform	Manual config	Manual config	Dashboard toggle
AI credits included	No (BYOK)	No (BYOK)	No (BYOK)

---

When Docker Still Makes Sense

Docker isn't always wrong for OpenClaw. It makes sense when:

• You're already running Docker for other services and have the infrastructure sorted
• You want reproducible deploys — docker compose up is the same everywhere
• You run multiple OpenClaw instances — Docker makes it easy to isolate them
• You need specific environment isolation — Maybe you're running OpenClaw alongside other apps that need conflicting dependencies

If Docker is already part of your workflow and you understand it, use it. The problems above are solvable. But if Docker is new to you and you're only using it because the OpenClaw docs said to — it's optional, and simpler alternatives exist.

---

FAQ

Does OpenClaw require Docker?

No. Docker is one installation method, but OpenClaw runs natively on Node.js. You can install it directly on any Linux server (or macOS/Windows for development) with Node.js 20+ installed. The official docs emphasize Docker because it's the most reproducible method, but it's not a requirement.

What are the minimum server requirements for OpenClaw with Docker?

2GB RAM minimum (Docker adds ~200MB overhead on top of OpenClaw's own usage). A 2 vCPU server is recommended. You need a KVM-based VPS — OpenVZ won't work with Docker. Storage needs are minimal (under 1GB for OpenClaw itself, though conversation logs grow over time).

How do I update OpenClaw in Docker without losing data?

Back up your data directory and .env file before any upgrade. Pin your Docker image to specific versions instead of using latest. Pull the new version, start it, and check the logs. If something breaks, restore your backup and revert to the previous image version. Full steps are in the upgrade section above.

Can I run OpenClaw without a VPS?

Yes. Managed hosting services like ClawdHost handle the server infrastructure for you. It costs $29/month and is BYOK (bring your own API key). You just connect your platform tokens and your agent is live — no server management required.

Why does my OpenClaw Docker container keep crashing?

The most common cause is running out of memory (OOM kill). Check with docker inspect openclaw | grep OOM. OpenClaw needs at least 1.5GB of available RAM when running in Docker. Add swap space and set memory limits in your docker-compose.yml to prevent uncontrolled memory growth. See Problem #4 above for the full fix.

Is Docker or bare metal better for OpenClaw?

For a single OpenClaw instance, bare metal (direct Node.js install) is simpler and uses less memory. Docker is better if you're already in a Docker-based workflow or need to run multiple isolated instances. Neither is wrong — it depends on your existing setup and comfort level.

---

Sources

• OpenClaw Installation Guide
• OpenClaw GitHub Repository
• Docker Compose Documentation
• PM2 Process Manager Docs
• Hetzner Cloud Pricing