2026 OpenClaw Official Docker: docker-setup.sh, GHCR & Control UI (18789) Runbook

About 13 min read · MACCOME

Audience: Engineers who read the official Docker docs yet bounce between local build timeouts, GHCR pull failures, port 18789 conflicts, and volume permissions that block Skills without a single ordered path from clone to Control UI. Outcome: Standardize on docker-setup.sh plus optional OPENCLAW_IMAGE, split work with the Docker production, Docker networking, and volume/permissions guides. Layout: six pitfalls, matrix, six-step runbook, triage table, three KPIs, closing guidance.

Why follow-the-docs still breaks on the Docker path

The official flow assumes consistent Docker Engine, Compose, disk, and egress. Mixing it with npm-global installs or another compose checkout disguises failures as “OpenClaw is broken.” Six frequent breakers in 2025–2026:

  1. Not separating source builds from GHCR pulls: forcing docker build on weak CI networks without switching to OPENCLAW_IMAGE.
  2. Stale containers still bound to 18789: previous compose trials not stopped, so the new docker-setup.sh cannot bind Control UI.
  3. UID/GID mismatch on volumes: container user vs host ~/.openclaw permissions—Skills/state writes fail while the UI looks “unresponsive.”
  4. Misreading pairing as image issues: WebSocket/token problems belong in the pairing/token article—not endless compose pull.
  5. Corporate proxy allows npm but blocks ghcr.io: mirror or allowlist hostnames; same class of diagnosis as the npm install runbook.
  6. Multiple checkouts sharing env/volumes: occasional stale tokens from mixed directories.

Table 1: Local build vs OPENCLAW_IMAGE (GHCR)

Pick one primary path in the change ticket and document rollback on the other—avoid verbal mixing.

DimensionDefault source buildOPENCLAW_IMAGE pulling GHCR
Best forCustom Dockerfile edits, build-cache debugging, or no ghcr egressFastest time-to-UI, constrained bandwidth, CI that caches images not repos
PrereqsEnough local CPU/RAM; multi-GB layer cache headroomReachable ghcr.io or internal mirror; pin tags beyond bare latest
RisksBuild timeouts, cache bloat, CPU contentionAuth/rate limits, tag drift, config skew vs binary
RollbackSwitch to prebuilt image while keeping the same data volume pathRevert to previous digest or return to source build; log compose changes
info

Note: Upstream repos evolve; commands below assume a checkout with docker-setup.sh at the repo root—record commit and script path if your fork differs.

Six-step runbook: clone to Control UI on 18789

  1. Preflight Docker: docker version and Compose v2; reserve disk for layers/volumes (align with the production resource table).
  2. Clone and enter the repo root: ensure docker-setup.sh is executable (chmod +x if needed).
  3. (Optional) Prebuilt image: export OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest—pin digest or stable tags in production instead of only moving tags.
  4. Run the script: ./docker-setup.sh; logs should show pull/build and compose up without an immediate non-zero exit.
  5. Open Control UI: browse http://127.0.0.1:18789 (if your revision changes the port, follow that build); verify the page loads, not connection refused.
  6. Shortest validation: run the documented health check in UI or CLI; for pairing, follow the pairing/token tree before changing app config.
bash
# Prefer GHCR prebuilt (replace tag per your policy)
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

# After success, Control UI should load (example port 18789)
# open http://127.0.0.1:18789

Table 2: Symptoms → checks (triage order)

Walk top to bottom; do not change image, network, and volumes simultaneously.

SymptomCheck firstAlso read
Build timeout / OOMSwitch to OPENCLAW_IMAGE; cap buildkit parallelism; prune cacheDocker production (resources)
401/403/TLS on pullProxy allowlists for ghcr.io; internal mirror—not the npm registry aloneNpm install runbook (proxy)
address already in use :18789docker ps for stale containers; stop old compose or remap port per docsDocker networking
Permission denied writing volumesHost UID/GID vs container user; named vs bind mountsVolume/Skills checklist
UI loads but channel silentRule out model/channel layers; then token/WS codesPairing/token

Three KPIs for change tickets and dashboards

  1. Image identity: log registry + tag + digest when available—not only “used latest”; roll back by digest.
  2. Control UI reachability: separate booleans for HTTP 200 / page title / health check from “container process exists.”
  3. Volume contract: map host ~/.openclaw (or team path) to compose mounts; snapshot size and permissions before/after upgrades.

If upstream release notes disagree, trust upstream; this article supplies engineering checkpoints.

Why a laptop trial rarely becomes production Gateway

Sleep, fragmented disks, and leftover Docker Desktop experiments fight dedicated CPU, stable egress, auditable volumes, and token boundaries. Ephemeral containers without pinned digests, volume contracts, or health checks fail on first real traffic.

Teams hosting Gateway long-term on stable Apple Silicon benefit from MACCOME cloud Macs with multi-region choice and flexible rental terms after this shortest loop—review public rental rates and the help center alongside Docker production and pairing articles.

Pilot: run all six steps on a dedicated remote host, record digest and volume snapshots, then decide monthly/quarterly terms and monitoring.

FAQ

Read this or Docker production first?

Use this runbook for the first successful UI path; use production for change windows, rollback, and monitoring. Rates: Mac mini rental rates.

Does OPENCLAW_IMAGE conflict with npm-global CLI?

Conflicts cluster around ports, env, and data dirs; keep one primary Gateway per host. Migration order: npm install runbook.

Can I expose 18789 publicly?

Put reverse proxy and TLS in front—review security sections in production/reverse-proxy articles instead of binding 0.0.0.0 blindly. Help: cloud Mac support and help center.