Install and Update OpenClaw on Ubuntu

Install Docker Engine and Compose v2 on Ubuntu, then run OpenClaw’s Compose deployment with persistent configuration and workspace directories. Before updating, back up those directories and verify that you can restore them with the previous release.

Verify Docker before adding OpenClaw

Use Docker’s Ubuntu installation guide to check that it supports your host release and architecture and to configure Docker’s package repository. Install Docker Engine and the Compose plugin from that repository. Run sudo systemctl status docker and confirm that the daemon is active before deploying OpenClaw. If it is inactive, the guide gives sudo systemctl start docker. Resolve any daemon startup error before investigating the application.

Review network exposure while the host is still empty. Docker’s Ubuntu guide warns that ports published by containers can bypass ufw or firewalld rules. For a first run, leave the Gateway off the public network and verify from a separate test machine that it is unreachable on the host’s public address. Check the published port bindings if it is reachable.

Capture the known-good image reference and persistent fixture before applying an upgrade. Reverting the image does not necessarily revert a file written by the newer application.

Install Docker Engine on Ubuntu | Docker Docs

Update the image with a restore point

Record the running release and its Compose settings before changing the image. Back up the Gateway state as OpenClaw’s Docker guide directs, along with any separately mounted workspace. Keep a protected copy of the settings required to reattach the same mounts. Select the intended release using the deployment’s documented image or build settings, and apply the change through Compose. Take a maintenance window for a single Gateway so old and new containers cannot write the same state concurrently.

In an illustrative rehearsal, assume one Gateway, one test channel, and a workspace containing a marker file. Verify the backup on a separate test deployment, update, and check that the new Gateway reaches a healthy state. Confirm the marker remains and the channel returns a fresh reply. If migration changes state and the release fails, stop it and restore the previous release with its matching backup.

After the rollback open the fixture and rerun one client-facing task. Matching the old version label is an earlier checkpoint than restoring working behavior.

Docker - OpenClaw

Use Compose status to narrow a failure

Run docker compose ps from the OpenClaw project directory after startup or an update. Compose reports service status and published ports. If a service repeatedly exits, examine its startup logs and check that the configured state and workspace paths are mounted and writable by the container user. If the service stays up but external messages get no reply, try a request through the Gateway itself to separate model access from channel delivery.

A Gateway that opens with first-run settings after an update may be looking at a different state directory. Stop the new container before completing onboarding, compare the old and new mount paths, and verify that the original backup is readable. After correcting the mount or restoring the backup, repeat the file and channel checks before reopening traffic.

How Compose works | Docker Docs

Sources