OpenClaw Docker Container Crashes on Restart — How to Fix (2026)

Diagnosing the Crash

1. Check Container Logs

# View recent logs
docker logs openclaw --tail 100

# Follow logs in real-time
docker logs openclaw -f

# Check container status
docker inspect openclaw --format='{{.State.Status}} {{.State.ExitCode}} {{.State.Error}}'

2. Check for OOM (Out of Memory) Kills

# Check if container was OOM killed
docker inspect openclaw | grep -i oom
# OOMKilled: true means the container ran out of memory

# Check system logs for OOM events
dmesg | grep -i "oom\|kill" | tail -20

Common Fixes

Fix 1: Increase Memory Limits

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    deploy:
      resources:
        limits:
          memory: 1G
        reservations:
          memory: 512M
    restart: unless-stopped

Fix 2: Validate Configuration Before Starting

# Validate your openclaw.json syntax
cat openclaw.json | python3 -m json.tool

# Check for common config issues
docker run --rm -v ./openclaw.json:/app/openclaw.json \
  ghcr.io/openclaw/openclaw:latest validate

Fix 3: Fix Volume Permissions

# Ensure data directory has correct permissions
chmod -R 755 ./data
chown -R 1000:1000 ./data

# Or use Docker user mapping
services:
  openclaw:
    user: "1000:1000"
    volumes:
      - ./data:/app/data

Fix 4: Clean Corrupted Data

# Backup then reset data directory
cp -r ./data ./data.backup
rm -rf ./data/cache ./data/sessions

# Restart the container
docker compose restart openclaw

Fix 5: Pin a Stable Image Version

services:
  openclaw:
    # Don't use :latest in production
    image: ghcr.io/openclaw/openclaw:v2.1.0
    restart: unless-stopped

Frequently Asked Questions

Why does my OpenClaw Docker container keep restarting?

The most common causes are: out-of-memory (OOM) kills, missing or invalid openclaw.json, corrupted data files, port conflicts, or incompatible Docker image versions. Check "docker logs" for the specific error.

How do I check why the container crashed?

Run "docker logs openclaw --tail 100" to see the last 100 lines of output. Also check "docker inspect openclaw | grep -i oom" to see if it was killed due to memory limits.

How much memory does OpenClaw need?

OpenClaw typically needs 256MB-512MB of RAM for basic operation. With heavy usage (many concurrent conversations, large context windows), it may need 1-2GB. Set Docker memory limits accordingly.

Should I use restart: always or restart: unless-stopped?

Use "restart: unless-stopped" for production. "restart: always" can cause infinite restart loops if there is a persistent configuration error. "unless-stopped" won't restart after you manually stop the container.

How do I prevent data corruption when the container crashes?

Use named Docker volumes instead of bind mounts for critical data. Named volumes handle filesystem caching better. Also consider enabling WAL mode if OpenClaw uses SQLite, and always mount config files as read-only (:ro) to prevent accidental overwrites.