OpenClaw Update Script Not Working — How to Fix (2026)

Common Update Failures

Docker Image Pull Fails

# Error: failed to pull image
# Fix: check network and disk space

# Check disk space
df -h

# Clean old Docker images
docker system prune -a --volumes

# Retry the pull
docker pull ghcr.io/openclaw/openclaw:latest

Permission Denied

# Error: permission denied
# Fix: run with sudo or add user to docker group

sudo docker compose pull
# Or permanently fix:
sudo usermod -aG docker $USER
# Then log out and back in

Config Incompatibility After Update

# Error: Invalid config / unknown field
# New versions may change config format

# Check migration guide
docker run --rm ghcr.io/openclaw/openclaw:latest migrate --dry-run

# Auto-migrate config
docker run --rm -v ./openclaw.json:/app/openclaw.json \
  ghcr.io/openclaw/openclaw:latest migrate

Safe Manual Update Process

Step 1: Backup Everything

# Create a backup BEFORE updating
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz \
  openclaw.json .env data/ plugins/ skills/

Step 2: Pull the New Image

docker pull ghcr.io/openclaw/openclaw:latest

Step 3: Check for Breaking Changes

# View the changelog
docker run --rm ghcr.io/openclaw/openclaw:latest changelog

# Or check the release notes online
# https://github.com/openclaw/openclaw/releases

Step 4: Stop and Recreate

# Using Docker Compose
docker compose down
docker compose up -d

# Using plain Docker
docker stop openclaw
docker rm openclaw
docker run -d --name openclaw \
  -p 3000:3000 \
  -v ./openclaw.json:/app/openclaw.json:ro \
  -v ./data:/app/data \
  --restart unless-stopped \
  ghcr.io/openclaw/openclaw:latest

Step 5: Verify the Update

# Check version
curl http://localhost:3000/api/health

# Check logs for errors
docker logs openclaw --tail 50

# Test basic functionality
curl -X POST http://localhost:3000/api/chat \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, are you updated?"}'

Rollback If Something Goes Wrong

# Stop the updated container
docker compose down

# Restore from backup
tar -xzf openclaw-backup-20260302.tar.gz -C /opt/openclaw/

# Use a specific older version
docker compose down
# Edit docker-compose.yml to pin the old version:
# image: ghcr.io/openclaw/openclaw:v2.0.5
docker compose up -d

Frequently Asked Questions

Why does the OpenClaw update script fail?

Common causes: network issues pulling the new Docker image, insufficient disk space, permission errors, the update script being outdated, or config file incompatibility with the new version.

How do I manually update OpenClaw?

Pull the latest image (docker pull ghcr.io/openclaw/openclaw:latest), stop the current container, then start a new one with the same volume mounts. Always backup before updating.

Can I rollback a failed update?

Yes. If you tagged the previous image or have a backup, you can rollback. Docker keeps old images locally: run "docker images" to find the previous version, then start a container with that image tag.

How do I check which version of OpenClaw I am running?

Run "openclaw --version" or check the Docker image tag: "docker inspect openclaw | grep Image". You can also check the /api/health endpoint which returns the version number.