diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4e251c9c357..cebf72c5021 100644
--- 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.
diff --git a/Dockerfile b/Dockerfile
index 8753631a7cf..40a5fbc2d8e 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -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
diff --git a/docker-compose.yml b/docker-compose.yml
index 8bc1d390b81..a17558157f7 100644
--- 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"
diff --git a/docker-setup.sh b/docker-setup.sh
index 71ae84d2afa..ce5e6a08f3d 100755
--- 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."
diff --git a/docs/install/docker.md b/docs/install/docker.md
index 6bab52cfc4e..42ce7a08d4d 100644
--- 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`:
diff --git a/src/docker-setup.e2e.test.ts b/src/docker-setup.e2e.test.ts
index defb5a2120a..df2848f0f67 100644
--- 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);