feat(docker): add opt-in sandbox support for Docker deployments (#29974)

* feat(docker): add opt-in sandbox support for Docker deployments Enable Docker-based sandbox isolation via OPENCLAW_SANDBOX=1 env var in docker-setup.sh. This is a prerequisite for agents.defaults.sandbox to function in any Docker deployment (self-hosted, Hostinger, DigitalOcean). Changes: - Dockerfile: add OPENCLAW_INSTALL_DOCKER_CLI build arg (~50MB, opt-in) - docker-compose.yml: add commented-out docker.sock mount with docs - docker-setup.sh: auto-detect Docker socket, inject mount, detect GID, build sandbox image, configure sandbox defaults, add group_add All changes are opt-in. Zero impact on existing deployments. Usage: OPENCLAW_SANDBOX=1 ./docker-setup.sh Closes #29933 Related: #7575, #7827, #28401, #10361, #12505, #28326 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address code review feedback on sandbox support - Persist OPENCLAW_SANDBOX, DOCKER_GID, OPENCLAW_INSTALL_DOCKER_CLI to .env via upsert_env so group_add survives re-runs - Show config set errors instead of swallowing them silently; report partial failure when sandbox config is incomplete - Warn when Dockerfile.sandbox is missing but sandbox config is still applied (sandbox image won't exist) - Fix non-canonical whitespace in apt sources.list entry by using printf instead of echo with line continuation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: remove `local` outside function and guard sandbox behind Docker CLI check - Remove `local` keyword from top-level `sandbox_config_ok` assignment which caused script exit under `set -euo pipefail` (bash `local` outside a function is an error) - Add Docker CLI prerequisite check for pre-built (non-local) images: runs `docker --version` inside the container and skips sandbox setup with a clear warning if the CLI is missing - Split sandbox block so config is only applied after prerequisites pass Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: defer docker.sock mount until sandbox prerequisites pass Move Docker socket mounting from the early setup phase (before image build/pull) to a dedicated compose overlay created only after: 1. Docker CLI is verified inside the container image 2. /var/run/docker.sock exists on the host Previously the socket was mounted optimistically at startup, leaving the host Docker daemon exposed even when sandbox setup was later skipped due to missing Docker CLI. Now the gateway starts without the socket, and a docker-compose.sandbox.yml overlay is generated only when all prerequisites pass. The gateway restart at the end of sandbox setup picks up both the socket mount and sandbox config. Also moves group_add from write_extra_compose() into the sandbox overlay, keeping all sandbox-specific compose configuration together. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs(docker): fix sandbox docs URL in setup output * Docker: harden sandbox setup fallback behavior * Tests: cover docker-setup sandbox edge paths * Docker: roll back sandbox mode on partial config failure * Tests: assert sandbox mode rollback on partial setup * Docs: document Docker sandbox bootstrap env controls * Changelog: credit Docker sandbox bootstrap hardening * Update CHANGELOG.md * Docker: verify Docker apt signing key fingerprint * Docker: avoid sandbox overlay deps during policy writes * Tests: assert no-deps sandbox rollback gateway recreate * Docs: mention OPENCLAW_INSTALL_DOCKER_CLI in Docker env vars --------- Co-authored-by: Jakub Karwowski <jakubkarwowski@Mac.lan> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Vincent Koc <vincentkoc@ieee.org>
2026-03-07 22:44:16 +00:00 · 2026-03-02 08:06:10 +01:00
parent f918b336d1
commit cb491dfde5
6 changed files with 348 additions and 0 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -52,6 +52,7 @@ Docs: https://docs.openclaw.ai
 - Browser/Profile defaults: prefer `openclaw` profile over `chrome` in headless/no-sandbox environments unless an explicit `defaultProfile` is configured. (#14944) Thanks @BenediktSchackenberg.
 - Browser/Remote CDP ownership checks: skip local-process ownership errors for non-loopback remote CDP profiles when HTTP is reachable but the websocket handshake fails, and surface the remote websocket attach/retry path instead. (#15582) Landed from contributor (#28780) Thanks @stubbi, @bsormagec, @unblockedgamesstudio and @vincentkoc.
 - Docker/Image health checks: add Dockerfile `HEALTHCHECK` that probes gateway `GET /healthz` so container runtimes can mark unhealthy instances without requiring auth credentials in the probe command. (#11478) Thanks @U-C4N and @vincentkoc.
+- Docker/Sandbox bootstrap hardening: make `OPENCLAW_SANDBOX` opt-in parsing explicit (`1|true|yes|on`), support custom Docker socket paths via `OPENCLAW_DOCKER_SOCKET`, defer docker.sock exposure until sandbox prerequisites pass, and reset/roll back persisted sandbox mode to `off` when setup is skipped or partially fails to avoid stale broken sandbox state. (#29974) Thanks @jamtujest and @vincentkoc.
 - Daemon/systemd checks in containers: treat missing `systemctl` invocations (including `spawn systemctl ENOENT`/`EACCES`) as unavailable service state during `is-enabled` checks, preventing container flows from failing with `Gateway service check failed` before install/status handling can continue. (#26089) Thanks @sahilsatralkar and @vincentkoc.
 - Android/Nodes reliability: reject `facing=both` when `deviceId` is set to avoid mislabeled duplicate captures, allow notification `open`/`reply` on non-clearable entries while still gating dismiss, trigger listener rebind before notification actions, and scale invoke-result ack timeout to invoke budget for large clip payloads. (#28260) Thanks @obviyus.
 - Windows/Plugin install: avoid `spawn EINVAL` on Windows npm/npx invocations by resolving to `node` + npm CLI scripts instead of spawning `.cmd` directly. Landed from contributor PR #31147 by @codertony. Thanks @codertony.
--- a/32
+++ b/32
@@ -57,6 +57,38 @@ RUN if [ -n "$OPENCLAW_INSTALL_BROWSER" ]; then \
      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
    fi

+# Optionally install Docker CLI for sandbox container management.
+# Build with: docker build --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1 ...
+# Adds ~50MB. Only the CLI is installed — no Docker daemon.
+# Required for agents.defaults.sandbox to function in Docker deployments.
+ARG OPENCLAW_INSTALL_DOCKER_CLI=""
+ARG OPENCLAW_DOCKER_GPG_FINGERPRINT="9DC858229FC7DD38854AE2D88D81803C0EBFCD88"
+RUN if [ -n "$OPENCLAW_INSTALL_DOCKER_CLI" ]; then \
+      apt-get update && \
+      DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        ca-certificates curl gnupg && \
+      install -m 0755 -d /etc/apt/keyrings && \
+      # Verify Docker apt signing key fingerprint before trusting it as a root key.
+      # Update OPENCLAW_DOCKER_GPG_FINGERPRINT when Docker rotates release keys.
+      curl -fsSL https://download.docker.com/linux/debian/gpg -o /tmp/docker.gpg.asc && \
+      expected_fingerprint="$(printf '%s' "$OPENCLAW_DOCKER_GPG_FINGERPRINT" | tr '[:lower:]' '[:upper:]' | tr -d '[:space:]')" && \
+      actual_fingerprint="$(gpg --batch --show-keys --with-colons /tmp/docker.gpg.asc | awk -F: '$1 == \"fpr\" { print toupper($10); exit }')" && \
+      if [ -z "$actual_fingerprint" ] || [ "$actual_fingerprint" != "$expected_fingerprint" ]; then \
+        echo "ERROR: Docker apt key fingerprint mismatch (expected $expected_fingerprint, got ${actual_fingerprint:-<empty>})" >&2; \
+        exit 1; \
+      fi && \
+      gpg --dearmor -o /etc/apt/keyrings/docker.gpg /tmp/docker.gpg.asc && \
+      rm -f /tmp/docker.gpg.asc && \
+      chmod a+r /etc/apt/keyrings/docker.gpg && \
+      printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable\n' \
+        "$(dpkg --print-architecture)" > /etc/apt/sources.list.d/docker.list && \
+      apt-get update && \
+      DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
+        docker-ce-cli docker-compose-plugin && \
+      apt-get clean && \
+      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+    fi
+
 USER node
 COPY --chown=node:node . .
 # Normalize copied plugin/agent paths so plugin safety checks do not reject
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -12,6 +12,14 @@ services:
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
+      ## Uncomment the lines below to enable sandbox isolation
+      ## (agents.defaults.sandbox). Requires Docker CLI in the image
+      ## (build with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1) or use
+      ## docker-setup.sh with OPENCLAW_SANDBOX=1 for automated setup.
+      ## Set DOCKER_GID to the host's docker group GID (run: stat -c '%g' /var/run/docker.sock).
+      # - /var/run/docker.sock:/var/run/docker.sock
+    # group_add:
+    #   - "${DOCKER_GID:-999}"
    ports:
      - "${OPENCLAW_GATEWAY_PORT:-18789}:18789"
      - "${OPENCLAW_BRIDGE_PORT:-18790}:18790"
--- a/docker-setup.sh
+++ b/docker-setup.sh
@@ -7,6 +7,9 @@ EXTRA_COMPOSE_FILE="$ROOT_DIR/docker-compose.extra.yml"
 IMAGE_NAME="${OPENCLAW_IMAGE:-openclaw:local}"
 EXTRA_MOUNTS="${OPENCLAW_EXTRA_MOUNTS:-}"
 HOME_VOLUME_NAME="${OPENCLAW_HOME_VOLUME:-}"
+RAW_SANDBOX_SETTING="${OPENCLAW_SANDBOX:-}"
+SANDBOX_ENABLED=""
+DOCKER_SOCKET_PATH="${OPENCLAW_DOCKER_SOCKET:-}"

 fail() {
  echo "ERROR: $*" >&2
@@ -20,6 +23,15 @@ require_cmd() {
  fi
 }

+is_truthy_value() {
+  local raw="${1:-}"
+  raw="$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')"
+  case "$raw" in
+    1 | true | yes | on) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 read_config_gateway_token() {
  local config_path="$OPENCLAW_CONFIG_DIR/openclaw.json"
  if [[ ! -f "$config_path" ]]; then
@@ -144,6 +156,16 @@ if ! docker compose version >/dev/null 2>&1; then
  exit 1
 fi

+if [[ -z "$DOCKER_SOCKET_PATH" && "${DOCKER_HOST:-}" == unix://* ]]; then
+  DOCKER_SOCKET_PATH="${DOCKER_HOST#unix://}"
+fi
+if [[ -z "$DOCKER_SOCKET_PATH" ]]; then
+  DOCKER_SOCKET_PATH="/var/run/docker.sock"
+fi
+if is_truthy_value "$RAW_SANDBOX_SETTING"; then
+  SANDBOX_ENABLED="1"
+fi
+
 OPENCLAW_CONFIG_DIR="${OPENCLAW_CONFIG_DIR:-$HOME/.openclaw}"
 OPENCLAW_WORKSPACE_DIR="${OPENCLAW_WORKSPACE_DIR:-$HOME/.openclaw/workspace}"

@@ -159,6 +181,9 @@ fi
 if contains_disallowed_chars "$EXTRA_MOUNTS"; then
  fail "OPENCLAW_EXTRA_MOUNTS cannot contain control characters."
 fi
+if [[ -n "$SANDBOX_ENABLED" ]]; then
+  validate_mount_path_value "OPENCLAW_DOCKER_SOCKET" "$DOCKER_SOCKET_PATH"
+fi

 mkdir -p "$OPENCLAW_CONFIG_DIR"
 mkdir -p "$OPENCLAW_WORKSPACE_DIR"
@@ -178,6 +203,15 @@ export OPENCLAW_DOCKER_APT_PACKAGES="${OPENCLAW_DOCKER_APT_PACKAGES:-}"
 export OPENCLAW_EXTRA_MOUNTS="$EXTRA_MOUNTS"
 export OPENCLAW_HOME_VOLUME="$HOME_VOLUME_NAME"
 export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS="${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}"
+export OPENCLAW_SANDBOX="$SANDBOX_ENABLED"
+export OPENCLAW_DOCKER_SOCKET="$DOCKER_SOCKET_PATH"
+
+# Detect Docker socket GID for sandbox group_add.
+DOCKER_GID=""
+if [[ -n "$SANDBOX_ENABLED" && -S "$DOCKER_SOCKET_PATH" ]]; then
+  DOCKER_GID="$(stat -c '%g' "$DOCKER_SOCKET_PATH" 2>/dev/null || stat -f '%g' "$DOCKER_SOCKET_PATH" 2>/dev/null || echo "")"
+fi
+export DOCKER_GID

 if [[ -z "${OPENCLAW_GATEWAY_TOKEN:-}" ]]; then
  EXISTING_CONFIG_TOKEN="$(read_config_gateway_token || true)"
@@ -255,6 +289,14 @@ YAML
  fi
 }

+# When sandbox is requested, ensure Docker CLI build arg is set for local builds.
+# Docker socket mount is deferred until sandbox prerequisites are verified.
+if [[ -n "$SANDBOX_ENABLED" ]]; then
+  if [[ -z "${OPENCLAW_INSTALL_DOCKER_CLI:-}" ]]; then
+    export OPENCLAW_INSTALL_DOCKER_CLI=1
+  fi
+fi
+
 VALID_MOUNTS=()
 if [[ -n "$EXTRA_MOUNTS" ]]; then
  IFS=',' read -r -a mounts <<<"$EXTRA_MOUNTS"
@@ -279,6 +321,9 @@ fi
 for compose_file in "${COMPOSE_FILES[@]}"; do
  COMPOSE_ARGS+=("-f" "$compose_file")
 done
+# Keep a base compose arg set without sandbox overlay so rollback paths can
+# force a known-safe gateway service definition (no docker.sock mount).
+BASE_COMPOSE_ARGS=("${COMPOSE_ARGS[@]}")
 COMPOSE_HINT="docker compose"
 for compose_file in "${COMPOSE_FILES[@]}"; do
  COMPOSE_HINT+=" -f ${compose_file}"
@@ -333,12 +378,17 @@ upsert_env "$ENV_FILE" \
  OPENCLAW_EXTRA_MOUNTS \
  OPENCLAW_HOME_VOLUME \
  OPENCLAW_DOCKER_APT_PACKAGES \
+  OPENCLAW_SANDBOX \
+  OPENCLAW_DOCKER_SOCKET \
+  DOCKER_GID \
+  OPENCLAW_INSTALL_DOCKER_CLI \
  OPENCLAW_ALLOW_INSECURE_PRIVATE_WS

 if [[ "$IMAGE_NAME" == "openclaw:local" ]]; then
  echo "==> Building Docker image: $IMAGE_NAME"
  docker build \
    --build-arg "OPENCLAW_DOCKER_APT_PACKAGES=${OPENCLAW_DOCKER_APT_PACKAGES}" \
+    --build-arg "OPENCLAW_INSTALL_DOCKER_CLI=${OPENCLAW_INSTALL_DOCKER_CLI:-}" \
    -t "$IMAGE_NAME" \
    -f "$ROOT_DIR/Dockerfile" \
    "$ROOT_DIR"
@@ -399,6 +449,115 @@ echo ""
 echo "==> Starting gateway"
 docker compose "${COMPOSE_ARGS[@]}" up -d openclaw-gateway

+# --- Sandbox setup (opt-in via OPENCLAW_SANDBOX=1) ---
+if [[ -n "$SANDBOX_ENABLED" ]]; then
+  echo ""
+  echo "==> Sandbox setup"
+
+  # Build sandbox image if Dockerfile.sandbox exists.
+  if [[ -f "$ROOT_DIR/Dockerfile.sandbox" ]]; then
+    echo "Building sandbox image: openclaw-sandbox:bookworm-slim"
+    docker build \
+      -t "openclaw-sandbox:bookworm-slim" \
+      -f "$ROOT_DIR/Dockerfile.sandbox" \
+      "$ROOT_DIR"
+  else
+    echo "WARNING: Dockerfile.sandbox not found in $ROOT_DIR" >&2
+    echo "  Sandbox config will be applied but no sandbox image will be built." >&2
+    echo "  Agent exec may fail if the configured sandbox image does not exist." >&2
+  fi
+
+  # Defense-in-depth: verify Docker CLI in the running image before enabling
+  # sandbox. This avoids claiming sandbox is enabled when the image cannot
+  # launch sandbox containers.
+  if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --entrypoint docker openclaw-gateway --version >/dev/null 2>&1; then
+    echo "WARNING: Docker CLI not found inside the container image." >&2
+    echo "  Sandbox requires Docker CLI. Rebuild with --build-arg OPENCLAW_INSTALL_DOCKER_CLI=1" >&2
+    echo "  or use a local build (OPENCLAW_IMAGE=openclaw:local). Skipping sandbox setup." >&2
+    SANDBOX_ENABLED=""
+  fi
+fi
+
+# Apply sandbox config only if prerequisites are met.
+if [[ -n "$SANDBOX_ENABLED" ]]; then
+  # Mount Docker socket via a dedicated compose overlay. This overlay is
+  # created only after sandbox prerequisites pass, so the socket is never
+  # exposed when sandbox cannot actually run.
+  if [[ -S "$DOCKER_SOCKET_PATH" ]]; then
+    SANDBOX_COMPOSE_FILE="$ROOT_DIR/docker-compose.sandbox.yml"
+    cat >"$SANDBOX_COMPOSE_FILE" <<YAML
+services:
+  openclaw-gateway:
+    volumes:
+      - ${DOCKER_SOCKET_PATH}:/var/run/docker.sock
+YAML
+    if [[ -n "${DOCKER_GID:-}" ]]; then
+      cat >>"$SANDBOX_COMPOSE_FILE" <<YAML
+    group_add:
+      - "${DOCKER_GID}"
+YAML
+    fi
+    COMPOSE_ARGS+=("-f" "$SANDBOX_COMPOSE_FILE")
+    echo "==> Sandbox: added Docker socket mount"
+  else
+    echo "WARNING: OPENCLAW_SANDBOX enabled but Docker socket not found at $DOCKER_SOCKET_PATH." >&2
+    echo "  Sandbox requires Docker socket access. Skipping sandbox setup." >&2
+    SANDBOX_ENABLED=""
+  fi
+fi
+
+if [[ -n "$SANDBOX_ENABLED" ]]; then
+  # Enable sandbox in OpenClaw config.
+  sandbox_config_ok=true
+  if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \
+    config set agents.defaults.sandbox.mode "non-main" >/dev/null; then
+    echo "WARNING: Failed to set agents.defaults.sandbox.mode" >&2
+    sandbox_config_ok=false
+  fi
+  if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \
+    config set agents.defaults.sandbox.scope "agent" >/dev/null; then
+    echo "WARNING: Failed to set agents.defaults.sandbox.scope" >&2
+    sandbox_config_ok=false
+  fi
+  if ! docker compose "${COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \
+    config set agents.defaults.sandbox.workspaceAccess "none" >/dev/null; then
+    echo "WARNING: Failed to set agents.defaults.sandbox.workspaceAccess" >&2
+    sandbox_config_ok=false
+  fi
+
+  if [[ "$sandbox_config_ok" == true ]]; then
+    echo "Sandbox enabled: mode=non-main, scope=agent, workspaceAccess=none"
+    echo "Docs: https://docs.openclaw.ai/gateway/sandboxing"
+    # Restart gateway with sandbox compose overlay to pick up socket mount + config.
+    docker compose "${COMPOSE_ARGS[@]}" up -d openclaw-gateway
+  else
+    echo "WARNING: Sandbox config was partially applied. Check errors above." >&2
+    echo "  Skipping gateway restart to avoid exposing Docker socket without a full sandbox policy." >&2
+    if ! docker compose "${BASE_COMPOSE_ARGS[@]}" run --rm --no-deps openclaw-cli \
+      config set agents.defaults.sandbox.mode "off" >/dev/null; then
+      echo "WARNING: Failed to roll back agents.defaults.sandbox.mode to off" >&2
+    else
+      echo "Sandbox mode rolled back to off due to partial sandbox config failure."
+    fi
+    if [[ -n "${SANDBOX_COMPOSE_FILE:-}" ]]; then
+      rm -f "$SANDBOX_COMPOSE_FILE"
+    fi
+    # Ensure gateway service definition is reset without sandbox overlay mount.
+    docker compose "${BASE_COMPOSE_ARGS[@]}" up -d --force-recreate openclaw-gateway
+  fi
+else
+  # Keep reruns deterministic: if sandbox is not active for this run, reset
+  # persisted sandbox mode so future execs do not require docker.sock by stale
+  # config alone.
+  if ! docker compose "${COMPOSE_ARGS[@]}" run --rm openclaw-cli \
+    config set agents.defaults.sandbox.mode "off" >/dev/null; then
+    echo "WARNING: Failed to reset agents.defaults.sandbox.mode to off" >&2
+  fi
+  if [[ -f "$ROOT_DIR/docker-compose.sandbox.yml" ]]; then
+    rm -f "$ROOT_DIR/docker-compose.sandbox.yml"
+  fi
+fi
+
 echo ""
 echo "Gateway running with host port mapping."
 echo "Access from tailnet devices via the host's tailnet IP."
--- a/docs/install/docker.md
+++ b/docs/install/docker.md
@@ -59,6 +59,9 @@ Optional env vars:
 - `OPENCLAW_DOCKER_APT_PACKAGES` — install extra apt packages during build
 - `OPENCLAW_EXTRA_MOUNTS` — add extra host bind mounts
 - `OPENCLAW_HOME_VOLUME` — persist `/home/node` in a named volume
+- `OPENCLAW_SANDBOX` — opt in to Docker gateway sandbox bootstrap. Only explicit truthy values enable it: `1`, `true`, `yes`, `on`
+- `OPENCLAW_INSTALL_DOCKER_CLI` — build arg passthrough for local image builds (`1` installs Docker CLI in the image). `docker-setup.sh` sets this automatically when `OPENCLAW_SANDBOX=1` for local builds.
+- `OPENCLAW_DOCKER_SOCKET` — override Docker socket path (default: `DOCKER_HOST=unix://...` path, else `/var/run/docker.sock`)
 - `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` — break-glass: allow trusted private-network
  `ws://` targets for CLI/onboarding client paths (default is loopback-only)

@@ -68,6 +71,38 @@ After it finishes:
 - Paste the token into the Control UI (Settings → token).
 - Need the URL again? Run `docker compose run --rm openclaw-cli dashboard --no-open`.

+### Enable agent sandbox for Docker gateway (opt-in)
+
+`docker-setup.sh` can also bootstrap `agents.defaults.sandbox.*` for Docker
+deployments.
+
+Enable with:
+
+```bash
+export OPENCLAW_SANDBOX=1
+./docker-setup.sh
+```
+
+Custom socket path (for example rootless Docker):
+
+```bash
+export OPENCLAW_SANDBOX=1
+export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
+./docker-setup.sh
+```
+
+Notes:
+
+- The script mounts `docker.sock` only after sandbox prerequisites pass.
+- If sandbox setup cannot be completed, the script resets
+  `agents.defaults.sandbox.mode` to `off` to avoid stale/broken sandbox config
+  on reruns.
+- If `Dockerfile.sandbox` is missing, the script prints a warning and continues;
+  build `openclaw-sandbox:bookworm-slim` with `scripts/sandbox-setup.sh` if
+  needed.
+- For non-local `OPENCLAW_IMAGE` values, the image must already contain Docker
+  CLI support for sandbox execution.
+
 ### Automation/CI (non-interactive, no TTY noise)

 For scripts and CI, disable Compose pseudo-TTY allocation with `-T`:
--- a/src/docker-setup.e2e.test.ts
+++ b/src/docker-setup.e2e.test.ts
@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { chmod, copyFile, mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,14 +19,23 @@ async function writeDockerStub(binDir: string, logPath: string) {
  const stub = `#!/usr/bin/env bash
 set -euo pipefail
 log="$DOCKER_STUB_LOG"
+fail_match="\${DOCKER_STUB_FAIL_MATCH:-}"
 if [[ "\${1:-}" == "compose" && "\${2:-}" == "version" ]]; then
  exit 0
 fi
 if [[ "\${1:-}" == "build" ]]; then
+  if [[ -n "$fail_match" && "$*" == *"$fail_match"* ]]; then
+    echo "build-fail $*" >>"$log"
+    exit 1
+  fi
  echo "build $*" >>"$log"
  exit 0
 fi
 if [[ "\${1:-}" == "compose" ]]; then
+  if [[ -n "$fail_match" && "$*" == *"$fail_match"* ]]; then
+    echo "compose-fail $*" >>"$log"
+    exit 1
+  fi
  echo "compose $*" >>"$log"
  exit 0
 fi
@@ -103,6 +113,30 @@ function runDockerSetup(
  });
 }

+async function withUnixSocket<T>(socketPath: string, run: () => Promise<T>): Promise<T> {
+  const server = createServer();
+  await new Promise<void>((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off("listening", onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off("error", onError);
+      resolve();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(socketPath);
+  });
+
+  try {
+    return await run();
+  } finally {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+    await rm(socketPath, { force: true });
+  }
+}
+
 function resolveBashForCompatCheck(): string | null {
  for (const candidate of ["/bin/bash", "bash"]) {
    const probe = spawnSync(candidate, ["-c", "exit 0"], { encoding: "utf8" });
@@ -216,6 +250,85 @@ describe("docker-setup.sh", () => {
    expect(envFile).toContain("OPENCLAW_GATEWAY_TOKEN=config-token-123");
  });

+  it("treats OPENCLAW_SANDBOX=0 as disabled", async () => {
+    const activeSandbox = requireSandbox(sandbox);
+    await writeFile(activeSandbox.logPath, "");
+
+    const result = runDockerSetup(activeSandbox, {
+      OPENCLAW_SANDBOX: "0",
+    });
+
+    expect(result.status).toBe(0);
+    const envFile = await readFile(join(activeSandbox.rootDir, ".env"), "utf8");
+    expect(envFile).toContain("OPENCLAW_SANDBOX=");
+
+    const log = await readFile(activeSandbox.logPath, "utf8");
+    expect(log).toContain("--build-arg OPENCLAW_INSTALL_DOCKER_CLI=");
+    expect(log).not.toContain("--build-arg OPENCLAW_INSTALL_DOCKER_CLI=1");
+    expect(log).toContain("config set agents.defaults.sandbox.mode off");
+  });
+
+  it("resets stale sandbox mode and overlay when sandbox is not active", async () => {
+    const activeSandbox = requireSandbox(sandbox);
+    await writeFile(activeSandbox.logPath, "");
+    await writeFile(
+      join(activeSandbox.rootDir, "docker-compose.sandbox.yml"),
+      "services:\n  openclaw-gateway:\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n",
+    );
+
+    const result = runDockerSetup(activeSandbox, {
+      OPENCLAW_SANDBOX: "1",
+      DOCKER_STUB_FAIL_MATCH: "--entrypoint docker openclaw-gateway --version",
+    });
+
+    expect(result.status).toBe(0);
+    expect(result.stderr).toContain("Sandbox requires Docker CLI");
+    const log = await readFile(activeSandbox.logPath, "utf8");
+    expect(log).toContain("config set agents.defaults.sandbox.mode off");
+    await expect(stat(join(activeSandbox.rootDir, "docker-compose.sandbox.yml"))).rejects.toThrow();
+  });
+
+  it("skips sandbox gateway restart when sandbox config writes fail", async () => {
+    const activeSandbox = requireSandbox(sandbox);
+    await writeFile(activeSandbox.logPath, "");
+    const socketPath = join(activeSandbox.rootDir, "sandbox.sock");
+
+    await withUnixSocket(socketPath, async () => {
+      const result = runDockerSetup(activeSandbox, {
+        OPENCLAW_SANDBOX: "1",
+        OPENCLAW_DOCKER_SOCKET: socketPath,
+        DOCKER_STUB_FAIL_MATCH: "config set agents.defaults.sandbox.scope",
+      });
+
+      expect(result.status).toBe(0);
+      expect(result.stderr).toContain("Failed to set agents.defaults.sandbox.scope");
+      expect(result.stderr).toContain("Skipping gateway restart to avoid exposing Docker socket");
+
+      const log = await readFile(activeSandbox.logPath, "utf8");
+      const gatewayStarts = log
+        .split("\n")
+        .filter(
+          (line) =>
+            line.includes("compose") &&
+            line.includes(" up -d") &&
+            line.includes("openclaw-gateway"),
+        );
+      expect(gatewayStarts).toHaveLength(2);
+      expect(log).toContain(
+        "run --rm --no-deps openclaw-cli config set agents.defaults.sandbox.mode non-main",
+      );
+      expect(log).toContain("config set agents.defaults.sandbox.mode off");
+      const forceRecreateLine = log
+        .split("\n")
+        .find((line) => line.includes("up -d --force-recreate openclaw-gateway"));
+      expect(forceRecreateLine).toBeDefined();
+      expect(forceRecreateLine).not.toContain("docker-compose.sandbox.yml");
+      await expect(
+        stat(join(activeSandbox.rootDir, "docker-compose.sandbox.yml")),
+      ).rejects.toThrow();
+    });
+  });
+
  it("rejects injected multiline OPENCLAW_EXTRA_MOUNTS values", async () => {
    const activeSandbox = requireSandbox(sandbox);