openclaw - 💡(How to fix) Fix [Feature]: Add --offline flag to scripts/docker/setup.sh for airgapped re-runs with a pre-loaded image [1 participants]

Summary

Add a --offline flag to scripts/docker/setup.sh so operators on airgapped hosts can re-run the full setup routine after transferring the OpenClaw image out-of-band (e.g. via USB or an internal artifact bundle) and loading it with docker load.

Problem to solve

scripts/docker/setup.sh unconditionally runs docker build or docker pull before anything else. On airgapped, offline-first, or high-compliance hosts the image is transferred out-of-band (USB, signed artifact bundle, internal registry snapshot) and imported with docker load. The image is already present locally, but the script still aborts at the build/pull step because there is no network egress.

The critical point is that operators in these environments do want to run the rest of the setup routine — they are not trying to bypass it. They need it to:

• pick up new env-var defaults and validation rules after upgrading the repo,
• refresh .env via upsert_env so compose stays in sync with the new release,
• fix data-directory permissions (chown pass) against the refreshed image,
• re-run onboard and sync_gateway_config for gateway mode/bind/token changes,
• reapply sandbox compose overlays and config pins.

Today the only options on an airgapped host are forking the script, commenting out the build/pull branch, or skipping setup entirely and running docker compose up by hand — all of which cause drift from the supported install path.

Proposed solution

Add a single explicit opt-in flag, --offline, parsed from $@ at the top of the script. When set:

• Skip docker build and docker pull.
• Verify the image exists locally via docker image inspect "$OPENCLAW_IMAGE". If not, fail with a clear message pointing at docker load as the intended way to install it.
• Apply the same skip for the optional sandbox image (openclaw-sandbox:bookworm-slim) and warn, not fail, if it is missing — matching the current non-offline branch's tone.
• Leave every other step in the script unchanged: env validation, mount validation, upsert_env, permission fix-up, run_prestart_cli onboard, sync_gateway_config, docker compose up -d, sandbox overlay handling.

Without --offline, the script is byte-for-byte identical to today. The flag is a strict subset-of-behavior change, not a new code path for the default case.

Alternatives considered

• OPENCLAW_OFFLINE=1 env var instead of a flag. Works, but a CLI flag is easier to spot in shell history and CI logs, and matches the --offline convention already used by npm install --offline, apt-get --no-download, cargo --offline, etc.
• Skip setup entirely and run docker compose up manually. Bypasses onboarding, loses sandbox overlay generation, skips .env synchronization, drifts further from the supported install path on every upgrade — this is what the feature is trying to avoid.
• Stand up a private registry inside the airgap. Requires extra infrastructure for organizations whose threat model is explicitly "no inbound artifacts except approved USB drops." Not a fit for one-shot or small-deployment airgapped installs.

Impact

• Affected: operators running OpenClaw in airgapped, offline-first, or high-compliance environments (defense, finance, OT/ICS, classified labs, hospitals with strict egress policies). Also useful for CI pipelines that preload a pinned image and want to re-run setup deterministically without hitting a registry.
• Severity: blocks re-running setup.sh after the initial install on airgapped hosts. Current workaround is to fork/edit the script on every upgrade.
• Frequency: every setup re-run on those hosts — configuration changes, token rotation, sandbox reconfiguration, release upgrades.
• Consequence: script drift across hosts, airgapped deployments falling behind the supported install path, onboarding/sandbox fixes from the online branch not reachable without manual patching.

Evidence/examples

• Diff against main is ~12 lines of pure shell, fully guarded behind the explicit flag.
• Prior-art convention in npm install --offline, cargo --offline, apt-get --no-download, and ongoing docker compose offline discussions.
• Before/after transcripts on an airgapped VM (image loaded via docker load, setup re-run on a config change) can be provided on request.

Additional information

• Backward compatibility: fully backward-compatible. No new env vars, no config-key changes, no behavior change when --offline is not passed.
• Security surface: unchanged or smaller. The flag only skips network calls (docker pull) and the build step. It does not add mounts, capabilities, tokens, or network calls.
• Cross-platform: pure bash arg parse; nothing beyond what the script already uses.
• Scope boundary: --offline only. Keeping this separate from PR #69143 / issue #69314 (OPENCLAW_DOCKER_PLATFORM) per CONTRIBUTING.md's "one thing per PR" rule — even though both touch scripts/docker/setup.sh.
• Follow-up PR: will be AI-assisted and marked as such in title/body per the AI/Vibe-Coded PRs section of CONTRIBUTING.md, with prompts/session log available on request, lightly tested locally on a Docker Desktop host that simulates the airgap by dropping network egress on the setup shell.