Docker: docker-setup.sh or image build fails

Symptoms

• ./docker-setup.sh fails during docker build or pnpm build.
• The container starts but the gateway crashes immediately.
• You mounted extra paths but the container can’t see them (macOS/Windows).

Cause

Common causes:

• Missing system packages in the image for your workload (media tools, build tooling, etc.)
• Docker Desktop file sharing not enabled for the host path you mounted (macOS/Windows)
• Stale image layers / partial build artifacts
• Not enough disk space for images and build caches

Fix

1) Start from the supported flow

From the OpenClaw repo root:

./docker-setup.sh

2) Inspect logs (best signal)

docker compose logs -f openclaw-gateway

3) If you need extra system packages, install them during build

Set OPENCLAW_DOCKER_APT_PACKAGES, then rerun docker-setup.sh:

export OPENCLAW_DOCKER_APT_PACKAGES="ffmpeg build-essential"
./docker-setup.sh

4) If you use extra mounts (macOS/Windows), ensure paths are shared

If you set OPENCLAW_EXTRA_MOUNTS, Docker Desktop must be allowed to access those host paths.

After changing mounts, rerun:

./docker-setup.sh

5) Rebuild cleanly if the image is stale

docker compose down
docker build --no-cache -t openclaw:local -f Dockerfile .
docker compose up -d openclaw-gateway

Verify

• docker compose ps shows the gateway container running.
• docker compose logs openclaw-gateway shows the gateway reached a listening/ready state.
• If you have the host CLI available, run openclaw status --deep against the intended gateway.
• For browser access, use the tokenized dashboard entrypoint from setup or openclaw dashboard; if auth still fails, follow /guides/control-ui-auth-and-pairing.