Docker Compose operations and image maintenance

export OPENCLAW_SANDBOX=1./scripts/docker/setup.sh

Custom socket path (e.g. rootless Docker):

export OPENCLAW_SANDBOX=1export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock./scripts/docker/setup.sh

The script mounts docker.sock only after sandbox prerequisites pass. If sandbox setup can't complete, it resets agents.defaults.sandbox.mode to off. Codex code mode is disabled for turns where the OpenClaw sandbox is active (see Sandboxing § Docker backend); never mount the host Docker socket into agent sandbox containers.

Disable Compose pseudo-TTY allocation with -T:

docker compose run -T --rm openclaw-cli gateway probedocker compose run -T --rm openclaw-cli devices list --json

openclaw-cli uses network_mode: "service:openclaw-gateway" so CLI commands can reach the gateway over 127.0.0.1. Treat this as a shared trust boundary. The compose config drops NET_RAW/NET_ADMIN and enables no-new-privileges on both openclaw-gateway and openclaw-cli.

Some Docker Desktop setups fail DNS lookups from the shared-network openclaw-cli sidecar after NET_RAW is dropped, showing up as EAI_AGAIN during npm-backed commands like openclaw plugins install. Keep the default hardened compose file for normal operation. The override below restores default capabilities for the openclaw-cli container only — use it for the one-off command that needs registry access, not as your default invocation:

printf '%s\n' \  'services:' \  '  openclaw-cli:' \  '    cap_drop: !reset []' \  > docker-compose.cli-no-dropped-caps.local.yml docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>

If you already created a long-running openclaw-cli container, recreate it with the same override — docker compose exec/docker exec can't change Linux capabilities on an already-created container.

The image runs as node (uid 1000). If you see permission errors on /home/node/.openclaw, make sure your host bind mounts are owned by uid 1000:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

The same mismatch can show up as blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) followed by plugin present but blocked — the process uid and the mounted plugin directory owner disagree. Prefer running as the default uid 1000 and fixing the bind mount ownership. Only chown /path/to/openclaw-config/npm to root:root if you intentionally run OpenClaw as root long term.

Use the repo-root Dockerfile instead of replacing it with a shortened single-stage example. Its workspace-deps stage extracts the package manifests required by pnpm-workspace.yaml. Build and production dependency stages share those inputs and run separate frozen-lockfile installs. This keeps both dependency layers cacheable without omitting packages/*, selected extensions/*, or other required workspace metadata.

The runtime-assets stage inherits production-deps and overlays /app from runtime-build-output, a copy of build with dependency trees removed. This reuses the fresh production install's layers while preserving compiled workspace packages and native addon outputs. It does not run pnpm prune on dependencies inherited from an image layer; pnpm 12 can fail that operation with EXDEV on OverlayFS. The build target retains development dependencies for live-test containers.

The same Dockerfile preserves the production runtime contract: digest-pinned Node and Bun bases, non-root uid 1000, tini, the built-in health check, and the /usr/local/bin/openclaw symlink. Dependabot refreshes the reviewed base digests; do not replace them with floating FROM node:24-bookworm tags.

The default image is security-first and runs as non-root node. For a more full-featured container:

1. Persist /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
2. Bake system deps: export OPENCLAW_IMAGE_APT_PACKAGES="git curl jq"
3. Bake Python deps: export OPENCLAW_IMAGE_PIP_PACKAGES="requests==2.32.5 humanize==4.14.0"
4. Bake Playwright Chromium: export OPENCLAW_INSTALL_BROWSER=1, or use the official -browser image tag
5. Persist browser downloads and caches: use OPENCLAW_HOME_VOLUME or OPENCLAW_EXTRA_MOUNTS. OpenClaw auto-detects the image's Playwright-managed Chromium on Linux.

If you pick OpenAI Codex OAuth in the wizard, it opens a browser URL. In Docker or headless setups, copy the full redirect URL you land on and paste it back into the wizard to finish auth.

The runtime image uses node:24-bookworm-slim and runs tini as PID 1 so zombie processes are reaped and signals handled correctly in long-running containers. It publishes OCI base-image annotations including org.opencontainers.image.base.name and org.opencontainers.image.source. Dependabot refreshes the pinned Node base digest, and each build applies current Debian point-release updates. See OCI image annotations.