OpenClaw Docker Self-Hosting: The Migration Bug That Silently Corrupts Your AI Data

There is a serious bug in how OpenClaw handles Docker-based upgrades, and it has the potential to cause data loss and broken state that is frustratingly difficult to diagnose. GitHub issue #98565 — rated P1 and flagged for maintainer review — describes the problem clearly: when you update an OpenClaw container image while preserving the same state/config volume, the gateway starts directly without running pending version migrations.

This means your OpenClaw instance may be running new code against an old schema, silently producing corrupted session data, broken transcripts, and state files that the new version cannot correctly interpret.

The Bug in Plain English

Normally when you run openclaw upgrade from the CLI, it:

1. Detects the version change
2. Runs all pending database and state migrations
3. Only then starts the gateway

When you upgrade via Docker — replacing the container image while keeping the state volume — step 1 and 2 are skipped entirely. The container starts the gateway directly. The new code assumes the migrations have already run. They have not.

The result? The OpenClaw team's own classification says: impact: message-loss. Your conversation history and agent state can be silently corrupted.

Who Is Affected?

This bug affects anyone running OpenClaw in Docker with a persistent state volume — which is the standard recommended self-hosting method. If you have ever done any of the following, you may be affected:

• docker pull openclaw/openclaw:latest followed by container restart
• Updated the image tag in a docker-compose.yml and run docker compose up -d
• Used Watchtower or any automatic container updater

If your OpenClaw version has changed since you first set it up and you did not run openclaw upgrade manually on the state directory — you should check your logs for migration errors.

How to Check If You're Affected

Method 1: Check the Gateway Startup Logs

docker logs openclaw --since 24h | grep -i "migration"

If you see no migration output at all during startup after a version change, the migrations were skipped.

Method 2: Run Migrations Manually

The safest recovery path right now (while the official fix is pending) is to run the upgrade command manually against your state volume before starting the gateway:

docker run --rm \
  -v openclaw-state:/home/user/.config/openclaw \
  openclaw/openclaw:latest \
  openclaw upgrade

This forces the migration step to run before the gateway process starts.

Method 3: Disable Automatic Container Updates

If you are using Watchtower or similar, pause it until the official fix lands. Uncontrolled image updates are the most dangerous scenario for this bug.

The Deeper Problem: Docker Is Not the Best Way to Self-Host OpenClaw

This bug highlights a broader issue with containerized AI assistants: Docker abstracts away the upgrade lifecycle in ways that can silently skip critical maintenance steps. The OpenClaw team designed the upgrade system around the openclaw upgrade CLI command — Docker replaces that with image swaps that bypass the entire flow.

For production self-hosting, running OpenClaw directly on a VPS (bare metal Node.js + PM2, no Docker layer) gives you more control:

• npm-based upgrades run through the official upgrade path that triggers migrations correctly
• No image swaps — the version change is explicit and auditable in your shell history
• PM2 ecosystem — rolling restarts, log rotation, crash recovery without Docker overhead
• State files are on the host directly — easier to backup, inspect, and recover

The Right Way to Self-Host OpenClaw on a VPS

Here is the clean installation approach that avoids the migration bug entirely:

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

# Install OpenClaw globally
npm install -g openclaw

# First-time setup
openclaw setup

# Install PM2 for process management
npm install -g pm2

# Start the gateway via PM2
pm2 start "openclaw gateway" --name openclaw-gateway
pm2 startup && pm2 save

# Future upgrades — always use this, never docker pull
openclaw upgrade

With this setup, every upgrade goes through the official lifecycle. Migrations always run. Your state is safe.

Self-Host OpenClaw on SNBD HOST VPS — Ready in Minutes

SNBD HOST provides the ideal VPS environment for running OpenClaw without Docker risk:

• ✅ Ubuntu 22.04 pre-installed — Node.js 20 installs in one command
• ✅ NVMe SSD — OpenClaw state files and transcript storage are fast
• ✅ Hourly snapshots available — before any upgrade, snapshot your VPS. Worst case, roll back in seconds.
• ✅ Dedicated IP — consistent identity for your AI gateway
• ✅ Bangladesh + Singapore locations — pick the datacenter closest to your Anthropic/OpenAI API routes

The migration bug will be patched. But even after the patch, running on a VPS with proper backups means you have a safety net that Docker alone cannot give you.

→ Deploy OpenClaw on SNBD HOST VPS from ৳799/month

Summary

OpenClaw's Docker upgrade path has a confirmed P1 bug that skips database migrations, risking message loss and state corruption. The safest response right now is to run migrations manually before each container restart, disable automatic image updates, and consider migrating to a direct Node.js installation on a VPS where the upgrade lifecycle is fully under your control.

Self-hosting AI is powerful — but only when the infrastructure underneath it is solid.