A rollback-aware first run for OpenClaw in Docker

May 11, 2026 · 12 min read

People often treat Docker as the rollback plan. It is only one layer. A container can be removed and recreated quickly, while the state it mounted may contain configuration, credentials, SQLite databases, workspace files, and session history. Recreating the container does not rewind those changes.

A safer first run asks a smaller question: can you prove what changed, stop it without losing the state, and return to a known image without pretending that external side effects disappeared? The official OpenClaw Docker guide and its storage reference give the pieces. The useful work is keeping those pieces in the right order.

What rollback-aware means here

A rollback-aware first run gives every change a stop point. At each stop point, record the image reference, the Compose files in use, the host paths mounted into the containers, and the check that passed. Keep a separate note for provider credentials and any channel account you later connect.

• The image checkpoint tells you which code and base image ran.
• The state checkpoint tells you where configuration, databases, workspaces, and secrets live.
• The behavior checkpoint tells you whether the Gateway can start and answer one harmless request.
• The authority checkpoint tells you which ports, senders, tools, plugins, and host paths can cause side effects.

These are different recovery jobs. Recreating a container replaces a process. Restoring a backup rewinds persistent files and databases. Exposure recovery stops forwarding and may require credential rotation or channel relinking. No single Docker command performs all three.

Prepare a disposable Docker lane

OpenClaw lists Docker Desktop or Docker Engine with Docker Compose v2 as prerequisites. A local source-image build needs at least 6 GB of RAM; a pre-built image avoids that particular build requirement. You also need enough disk for images, logs, mounted state, and a backup.

Use a source checkout from the OpenClaw repository if you want to run the supplied setup script. Choose a provider account that is safe for a test session. Do not begin with production channel tokens, a shared workspace, or a host directory containing personal documents. If you use a model service running on the host, remember that 127.0.0.1 inside the container means the container itself. The Docker-specific address is usually host.docker.internal, as described in the networking documentation.

Before running setup, inspect the Compose files privately. docker compose config resolves overrides and interpolated values, but Docker warns that Compose files can read host files and request broad privileges. Treat the configuration as code you are about to run. Do not paste an unredacted result into an issue or chat.

Checkpoint 1: choose and record the image

The OpenClaw Docker guide supports local builds and pre-built images from the official GitHub Container Registry or Docker Hub mirror. It also warns against unofficial mirrors. For a rollback-aware run, use a version-specific tag rather than a moving tag such as latest. The OpenClaw Compose notes describe plain version and dated release tags as immutable, while Docker's Compose guidance explains that tags can move and digests are immutable.

export OPENCLAW_IMAGE='ghcr.io/openclaw/openclaw:replace-with-a-stable-version-tag'
./scripts/docker/setup.sh
docker compose ps
docker compose images
docker image inspect ghcr.io/openclaw/openclaw:replace-with-a-stable-version-tag

Replace the placeholder before running the command. Save the selected tag and the image ID or digest in your private run record. The digest is evidence of what the Docker daemon pulled; it is not a claim that the image or every plugin inside it is safe.

The documented setup flow prompts for provider API keys, generates a Gateway token, writes that token to the project .env file, creates the legacy auth-profile secret directory, and starts the Gateway through Compose. Keep the .env file private. If the setup script changes it unexpectedly, stop and compare the shell variables with the values you intended to use before starting another container.

Checkpoint 2: prove where state lives

OpenClaw's Docker storage documentation maps the configuration directory to /home/node/.openclaw, the workspace to a subdirectory below it, and the auth-profile secret directory to /home/node/.config/openclaw. The configuration area can contain openclaw.json, the shared SQLite database, agent databases, and the environment file. Current OAuth material may be stored as plaintext in SQLite, so the mounted configuration path and its backups are credential stores.

Inspect the running Gateway and verify that only the directories you selected are mounted:

docker compose ps
docker inspect $(docker compose ps -q openclaw-gateway)

Look at the Mounts section. Confirm the source paths belong to this disposable installation, confirm whether each mount is read-only or read-write, and check that the host path is not an accidental home-directory or system-directory mount. The OpenClaw documentation says unset path variables fall back below HOME, or below /tmp when HOME is missing. A first run that silently falls back to /tmp is a reason to stop and correct the environment.

Take a verified archive before experimenting with configuration or sandbox settings. The OpenClaw backup command is designed to capture committed database state rather than copying live SQLite files:

docker compose run --rm --volume /absolute/path/openclaw-first-run/backups:/backup openclaw-cli backup create --output /backup --verify

This is a proposed Docker wrapper around the documented openclaw backup create --output ... --verify operation. The /backup directory must map to a host location that is writable by the container user and outside the container's disposable filesystem. Never copy live .sqlite, -wal, -shm, or -journal files as a substitute for the supported backup path.

During diagnosis, use docker compose down only when you need to remove the containers and network. Do not add -v casually: Docker documents that down -v removes named volumes and anonymous volumes. A host bind mount is not deleted by that flag, but data already changed inside the bind mount remains changed.

Checkpoint 3: prove the Gateway before adding channels

Once the container is running, ask Compose for a dashboard URL:

docker compose run --rm openclaw-cli dashboard --no-open

Open the printed local URL, normally http://127.0.0.1:18789/, and paste the token from .env into the Control UI privately. The URL is a convenient local entry point, not proof that the Gateway is bound only to loopback. The Docker setup defaults to a LAN bind so the host can reach the published port, and OpenClaw's security documentation notes that container images use an exposed bind that must be paired with authentication.

Run the audit before connecting any messaging service:

docker compose run --rm openclaw-cli security audit

The audit checks network exposure, local disk hygiene, plugins, tool policy, sandbox drift, and assumptions about host execution. Treat a warning as a decision to document, not as a harmless decoration. The Gateway exposure runbook recommends returning to loopback-only access when you cannot explain who can reach the Gateway, how they authenticate, which agent they trigger, and which tools that agent can use.

Proposed behavior check. Put a short synthetic text file in the disposable workspace. Ask for a summary without asking OpenClaw to write, delete, browse, send, or call an external service. Record the provider, model, Gateway host, expected output, and actual output. Then restart the service:

docker compose restart openclaw-gateway
docker compose ps
docker compose logs --tail=100 openclaw-gateway

Reopen the dashboard and confirm that the session is still present and that the container returned to the expected image and mounts. This restart test is an operator check proposed by this article, not a claim that the author ran it. If the task cannot be explained or the post-restart state is unclear, leave channels disabled.

Keep the Gateway container separate from the agent sandbox

Dockerizing the Gateway and enabling OpenClaw's Docker agent sandbox are related but different choices. OpenClaw says sandboxing is off by default and does not require the Gateway itself to run in a container. When enabled, the Gateway runs agent tool execution in separate containers.

Enable it only after the basic Gateway checkpoint passes and you have another backup:

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh
docker compose run --rm openclaw-cli sandbox list --json

The documented Docker sandbox defaults are restrictive: network: 'none', readOnlyRoot: true, capDrop: ['ALL'], and no-new-privileges. A read-only workspace must be selected explicitly with the relevant workspace access setting. If a sandbox image is missing, the troubleshooting guide points to scripts/sandbox-setup.sh for a source checkout. Permission errors usually mean the mounted directory ownership does not match the image's UID 1000. A source build killed with exit 137 points to the documented memory requirement, not a reason to widen host permissions.

There is an important host boundary here. When the Gateway itself runs in Docker and orchestrates sibling sandbox containers, OpenClaw uses the host Docker socket. The Gateway configuration must refer to host absolute paths, and the Gateway container needs matching volume mappings. The documentation explicitly says not to mount the host Docker socket into an agent sandbox or custom Codex sandbox.

Sandboxing also has a narrower meaning than many first-run guides suggest. OpenClaw's capability matrix says sandbox backends isolate tool execution; they do not move the Gateway, native plugins, or control-plane RPC into the sandbox. A sandboxed shell is not the same thing as a completely host-free OpenClaw deployment.

What still belongs to the host

Docker's bind-mount documentation says bind mounts have write access to host files by default. Its Compose trust model says a Compose file can control host interaction through mounts, privileges, devices, host networking, and image selection. OpenClaw's storage and sandbox documents add the product-specific details.

On Docker Desktop, the daemon runs inside a Linux VM, while Docker provides mechanisms to share native host paths with containers. That changes the implementation detail, not the operator's responsibility to know which native folders are shared.

Rootless Docker can move the daemon and containers into a user namespace, but it does not remove the need to review mounts, Compose files, provider credentials, or network routes. On Linux, AppArmor and user-namespace policy can also affect sandbox startup. Use openclaw doctor to diagnose the documented probe failures before changing a host-wide kernel setting.

Failure paths that preserve evidence

If the container does not start

Start with docker compose ps and the Gateway logs. Keep the state directory and backup in place. If the error is EACCES, check the ownership of only the intended OpenClaw directories; the official Compose notes say the runtime uses UID 1000. If a sandbox image is missing, build or select the documented image. If a local source build exits with 137, use a pre-built image or a host with more memory.

If the image starts but the first task is wrong

Do not add channels or tools to make the test more interesting. Save the logs, stop the Gateway, and decide whether the problem is the image, configuration, provider, or workspace. If it is only an image or process problem, restore the known-good image reference in .env and recreate the service with the same Compose files:

docker compose down
docker compose up -d openclaw-gateway

Docker documents that Compose recreates changed services while preserving mounted volumes. This is a process rollback. It does not reverse configuration or database changes made by the newer image.

If persistent state needs to be restored

The supported OpenClaw restore path writes into a fresh staging target. It refuses a non-empty target, does not overwrite live state in place, and warns that archive verification checks structure but does not authenticate untrusted content. With an empty host-backed restore directory, a Docker wrapper can look like this:

docker compose run --rm --volume /absolute/path/openclaw-first-run/backups:/backup --volume /absolute/path/openclaw-first-run/restored:/restore openclaw-cli backup restore /backup/archive.tar.gz --target /restore

Stop the Gateway and any other writers before activation. Make a fresh backup of the current state or move it aside. Inspect the extracted files, then point the deployment at a new state path or perform the documented activation step. Do not replace the live mount from inside a running container.

OpenClaw's rollback documentation is explicit about the hard limit: downgrading the package does not reverse configuration or database migrations. A compatible, verified pre-update backup must be restored with its matching release when state has moved beyond the older format. During recovery, set OPENCLAW_NO_AUTO_UPDATE=1 so an updater does not immediately reapply the newer image.

State rollback can also change the outside world. The backup documentation warns that channel ratchet state, especially for WhatsApp, may desynchronize, while approvals and delivery or deduplication state roll back. Plugins may need to be reinstalled because plugin node_modules trees are not archived. If the Gateway was overexposed, stop public forwarding first, rotate Gateway and integration credentials, remove unexpected senders, review the audit trail, and rerun the deep audit.

When to move beyond the first run

Keep the installation in its disposable lane until you can answer these questions from your records:

1. Which exact image and Compose configuration ran?
2. Which host paths and volumes contain state?
3. Can the Gateway start and survive a controlled restart?
4. Which network surfaces and senders can reach it?
5. Which tools run in the Gateway, which run in a sandbox, and which still depend on the host?
6. Which backup would you restore, into which empty target, and with which matching release?

If one answer is missing, leave the Gateway stopped and keep the evidence. Docker has made the process replaceable. State, credentials, and authority still need deliberate boundaries.

Sources

All sources were opened and checked on 2026-09-13. Publication dates were not stated on the linked documentation pages.

1. Docker - OpenClaw · accessed 2026-09-13
2. Docker networking, providers, and storage - OpenClaw · accessed 2026-09-13
3. Docker Compose operations and image maintenance - OpenClaw · accessed 2026-09-13
4. Docker backend - OpenClaw · accessed 2026-09-13
5. Supported capability matrix - OpenClaw · accessed 2026-09-13
6. Security - OpenClaw · accessed 2026-09-13
7. Running the security audit - OpenClaw · accessed 2026-09-13
8. Gateway exposure runbook - OpenClaw · accessed 2026-09-13
9. Backups - OpenClaw · accessed 2026-09-13
10. Rollback and recovery - OpenClaw · accessed 2026-09-13
11. Bind mounts | Docker Docs · accessed 2026-09-13
12. Trust model for Compose files | Docker Docs · accessed 2026-09-13
13. docker compose up | Docker Docs · accessed 2026-09-13
14. docker compose down | Docker Docs · accessed 2026-09-13