How to update OpenClaw without breaking your agent

What must survive the update

The program and the agent’s data are different things. Replacing OpenClaw should retain configuration, credentials, conversations and workspace files. In Docker, only data stored outside the replaced container layer survives that replacement. Keep the existing volumes and bind mounts; do not delete them as part of an update. Programs or files installed only into the container layer are covered separately in what survives an OpenClaw image update.

The current backup command creates an archive of state, configuration, credentials, configured agent directories and, by default, workspaces:

openclaw backup create --output ~/Backups/openclaw --verify

Check that it succeeds and covers the locations you actually use. Keep the backup outside the container being replaced and protect it as you would the original credentials. Do not make a backup by copying live SQLite files: a running database can have committed data in its journal. An automatic configuration copy is not a full-state backup.

Package and source installations

Read the target release notes before changing versions, then use the native updater:

openclaw --version
openclaw update --dry-run
openclaw update

The updater detects the installation type. A successful managed update handles the Gateway restart and verification; an independently supervised or manually started process needs its actual supervisor. Inspect failures before retrying. In particular, an installed 2026.9.4 updater can stop at managed-service-preflight before the newer updater ever runs.

For that failure, use the official manual package-manager procedure from a separate terminal: preserve the installation owner, package manager, prefix and state; stop the Gateway through its real supervisor; replace the package; run Doctor; restart through that same supervisor. Do not ask the agent to run a package replacement inside the Gateway process hosting its own chat.

Docker: replace the image, retain the data

Use the Compose configuration that already runs your agent, including its override files and mounts. Select the new image version for both the Gateway and any CLI service used to maintain its state, pull it, then recreate the Gateway with the retained data. The Docker operations reference documents the service commands. A Compose restart alone does not replace a container with a newly selected image.

Read startup logs before declaring success. The new Gateway can perform startup-safe migrations, but some repairs require a separate Doctor run. If it exits on a repair instruction, repeated restarts do not complete that repair.

The 2026.9.1 → 2026.9.4 restart loop

missing or drifted index idx_agent_session_nodes_active
run openclaw doctor --fix to repair it

Replacing a 2026.9.1 image with 2026.9.4 over the same mounted state can leave the Gateway restarting in a loop on this error. The index exists in the new schema but not in 2026.9.1’s. Running the new version’s openclaw doctor --fix --non-interactive against that state repairs the one canonical index in under half a minute, and the next startup is ready within seconds, with sessions, memory and channels intact. The upstream issue records that exact update and result; it is not evidence that every image upgrade needs the repair.

Stop the Gateway before maintenance, use the new image and the same state mounts for Doctor, and start it again only after the repair succeeds. Do not delete the database or create the missing index by hand. If Doctor reports a different problem, follow that diagnostic instead.

A paused memory index is not erased memory

The same update leaves vector memory search paused, because OpenClaw’s chunking implementation changed. The documented behavior is that a normal search rebuilds this particular kind of stale index; a status check is read-only and does not. A paused status seen before any search has run therefore does not show that automatic rebuilding failed.

Check the reason with openclaw memory status. A changed embedding provider or an unavailable local embedding service is a different cause; use the memory-search diagnostic guide before forcing a rebuild. Never remove the agent database to clear an index warning.

Verify before considering rollback

Check the running version and Gateway health, send a message through the channel you use, and ask for something that requires a real memory search. Check a familiar workspace file or workflow too. A process that is running has not yet proved those parts survived.

If you need to go back, rolling back an OpenClaw update covers the order to do it in, and OpenClaw’s rollback instructions cover the versions involved. Restoring an older executable cannot undo a database migration. The pre-update backup is the recovery point, and restoring it can discard work done since it was taken.