OpenClaw Docker Deployment: Common Errors and Fixes

Docker Deployment Errors That Trip Up Everyone

Docker is the recommended way to self-host OpenClaw, but containers introduce their own category of problems. A misconfigured volume mount, an undersized memory limit, or a file permission issue can turn a five-minute setup into an hour-long debugging session.

This guide documents the most common Docker deployment errors for OpenClaw, what causes each one, and the exact commands to fix them. If you've been staring at a container that keeps restarting or exiting immediately, one of these is almost certainly your problem.

1. Container OOM Killed (Out of Memory)

OpenClaw runs a Node.js process that loads AI model connections, plugin systems, and manages conversation state. This requires more memory than many lightweight containers. If your container is being killed by the OOM (Out of Memory) killer, you'll see an exit code of 137 and messages like Killed in the logs.

The Fix

OpenClaw needs a minimum of 2 GB RAM with 3 GB swap. Many users try to run it with 512 MB or 1 GB, which causes intermittent OOM kills — especially during peak usage when multiple conversations are active.

Set the correct memory limits when starting your container:

• docker run --memory=2g --memory-swap=3g ...

The --memory-swap=3g flag means the container can use 2 GB of RAM plus 1 GB of swap space. This gives the process headroom during memory spikes without letting it consume all host memory.

Important: If your VPS has only 1 GB of total RAM, Docker memory limits won't help — the host itself will OOM kill the container. You need a server with at least 2 GB of RAM to run OpenClaw reliably.

2. Config File Not Found

OpenClaw expects its configuration file at ~/.openclaw/openclaw.json inside the container. The standard approach is to bind-mount a directory from the host into the container.

Correct Docker Run Command

• docker run -v /path/to/config:/home/node/.openclaw ...

Note that the container runs as the node user (uid 1000), so the internal path is /home/node/.openclaw, not /root/.openclaw.

Common Mistakes

• Mounting the file instead of the directory — Mount the parent directory, not the JSON file directly. OpenClaw writes additional files (credentials, session data) to the .openclaw directory at runtime.
• Wrong path inside container — Using /root/.openclaw instead of /home/node/.openclaw.
• File doesn't exist on host — Docker will create an empty directory if the source path doesn't exist, leading to a "config not found" error inside the container.

3. Permission Denied Errors

The OpenClaw container runs as the node user (uid 1000), not root. When you bind-mount a config directory from the host, the node user must have read and write access to that directory and all files within it.

The Fix

After creating your config directory on the host, set permissions explicitly:

1. Create the directory: mkdir -p /path/to/config
2. Set permissions: chmod 777 /path/to/config
3. If a config file already exists: chmod 666 /path/to/config/openclaw.json

Why chmod 777? Using chown 1000:1000 would be cleaner, but it requires root on the host. The chmod 777 approach works regardless of the host user. Also note that Node.js's mkdir with a mode parameter can be overridden by the system's umask — always use an explicit chmod after creating the directory.

Don't forget the credentials directory. If you're using dmPolicy: "pairing" for Telegram, the directory ~/.openclaw/credentials/ must exist inside the container. Without it, the Telegram plugin will silently drop all incoming messages with no error logged.

4. Port Already in Use

If you see an error like Bind for 0.0.0.0:18789 failed: port is already allocated, another process or container is already using that port on the host.

How to Diagnose

1. Find what's using the port: netstat -tlnp | grep 18789 (Linux) or lsof -i :18789 (macOS).
2. If it's an old container: docker ps -a | grep 18789 — then stop and remove it.
3. If it's another service, either stop that service or map the OpenClaw container to a different host port: -p 18790:18789.

5. Container Starts Then Immediately Exits

A container that starts and exits within seconds usually means the OpenClaw process crashed during initialization. The exit code and logs tell you why.

Debugging Steps

1. Check the exit code: docker inspect <container-id> --format='{{.State.ExitCode}}'
2. Read the logs: docker logs <container-id>

Common Exit Reasons

• Exit code 1 — Application error. Usually a config parse failure (invalid JSON) or a missing required field. Check the logs for the specific error message.
• Exit code 137 — OOM killed. See section 1 above.
• Exit code 139 — Segmentation fault. Rare, but can happen with incompatible Node.js versions. Use the official OpenClaw Docker image to avoid this.
• "SyntaxError: Unexpected token" — Your openclaw.json has invalid JSON. Common culprits: trailing commas, missing quotes around keys, or unescaped special characters. Validate your JSON with jq . openclaw.json before mounting it.

6. trustedProxies Not Working

If you're running OpenClaw behind a reverse proxy (Caddy, Nginx, Traefik), you need to configure trustedProxies so the gateway can see real client IPs. A common mistake is using CIDR notation.

Wrong

• "trustedProxies": ["172.17.0.0/16"] — CIDR ranges are not supported. OpenClaw's isTrustedProxyAddress() does a strict === string comparison.

Correct

• "trustedProxies": ["172.17.0.1"] — Use the exact IP of your Docker bridge gateway.

To find your Docker bridge IP, run: docker network inspect bridge | grep Gateway.

The Complete Docker Run Command

Here's a working docker run command that avoids all of the issues above:

• docker run -d --name openclaw \
• --memory=2g --memory-swap=3g \
• -p 18789:18789 \
• -v /home/user/openclaw-config:/home/node/.openclaw \
• ghcr.io/openclaw/openclaw:latest \
• node openclaw.mjs gateway --allow-unconfigured

Make sure /home/user/openclaw-config/ exists, has chmod 777, and contains a valid openclaw.json.

Skip Docker Entirely with Managed Hosting

Every issue in this guide — memory limits, file permissions, port conflicts, proxy configuration — disappears when you use OpenClaw Launch. The platform handles container orchestration, health monitoring, automatic restarts, and SSL termination. You configure your bot through a visual UI and click deploy.

No Docker knowledge required. Start at $3/month at openclawlaunch.com.