How Do I Enable the OpenClaw Sandbox? Modes, Images and How to Check

Published 2026-11-15 · Updated 2026-11-15 · By The Is My Agent Safe team

Short answer

To enable the OpenClaw sandbox, set agents.defaults.sandbox.mode to non-main or all, then build the default Docker image. Sandboxing is off by default. The Gateway stays on the host; only tool execution moves into the sandbox. After you change the config, run openclaw sandbox explain to see what is in effect, then stop the Gateway and run openclaw sandbox recreate --all so existing containers pick up the new settings. Then run openclaw gateway restart.

  • Sandboxing is off by default. Mode values are off, non-main and all.
  • The default backend is docker. Build the openclaw-sandbox:trixie-slim image before new sandboxes start.
  • workspaceAccess none (the default) keeps the agent workspace out of the sandbox.
  • openclaw sandbox explain shows the effective mode, mounts and tool policy.
  • Existing containers keep old settings until you run openclaw sandbox recreate.

Paste your audit: run openclaw security audit --deep and paste the output into our free check for a red/amber/green result with the most important finding first (Limits of the check).

Who this is for

OpenClaw owners who want tool commands to run in a container, not on the host.

How do I enable the OpenClaw sandbox?

OpenClaw's sandboxing docs say sandboxing is off by default. The Gateway process always stays on the host. Only tool execution moves into the sandbox when you turn it on. Their minimal enable example looks like this:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

Then build the default image (next section), run openclaw sandbox explain to confirm what is in effect, and recreate any existing sandbox containers.

What do the sandbox modes mean?

OpenClaw's mode docs name three independent settings:

non-main sandboxes every session except the agent's main session. Group and channel sessions use their own keys, so they always count as non-main and get sandboxed. That is the "common surprise" OpenClaw's sandbox vs tool policy docs mention. If you also want the main session sandboxed, use all.

A named operator role with sandbox: "required" still sandboxes that role's new sessions even when the agent mode is off. Elevated execution cannot bypass that requirement, and a missing backend blocks execution rather than falling back to the host.

How do I build the sandbox image?

The default Docker image is openclaw-sandbox:trixie-slim (images and setup). From a source checkout:

scripts/sandbox-setup.sh

From an npm install, first set the mode to non-main or all, then run openclaw doctor --fix and accept the image build. Doctor skips image checks when the mode is off. OpenClaw does not silently substitute a plain Debian image if the default image is missing.

By default, local container sandboxes run with no network. network: "host" is blocked. The audit checks list rates sandbox.dangerous_network_mode critical when a sandbox uses host or container:* network mode.

What can the sandbox see of my files?

workspaceAccess is none by default: tools use an isolated workspace under ~/.openclaw/sandboxes, and the agent workspace is not exposed (workspace access docs). ro mounts the agent workspace read-only at /agent. rw mounts it read/write at /workspace.

Bind mounts pierce that boundary. OpenClaw's sandbox vs tool policy docs say mounts default to read-write if you omit the mode, and mounting /var/run/docker.sock "effectively hands host control to the sandbox." The audit checks list rates sandbox.dangerous_bind_mount critical when a bind targets a blocked system path, a credential path or the Docker socket.

How do I check it's actually on?

openclaw sandbox explain
openclaw sandbox list

openclaw sandbox explain prints the effective mode, scope, workspace access, whether the session is currently sandboxed, the Docker mounts, and the sandbox tool policy (sandbox CLI docs).

Updating the config does not change running containers. Existing runtimes keep their old settings, and idle runtimes are only pruned after prune.idleHours (default 24 hours). Regularly used agents can keep stale runtimes alive. Recreate them after a config or image change:

openclaw gateway stop
openclaw sandbox recreate --all
openclaw gateway restart

If the Gateway is running, recreate refuses. Runtimes are rebuilt on the next use. Then run openclaw security audit --deep. Findings that point at sandbox settings include sandbox.docker_config_mode_off (Docker config is present but mode is off) and sandbox.dangerous_bind_mount.

What still runs outside the sandbox?

Tool policy still applies first. If a tool is denied, sandboxing does not bring it back. tools.elevated is an exec-only escape hatch that runs exec outside the sandbox, except when a creator role requires a sandbox. See the permissions checklist to keep elevated off and trim tools. OpenClaw's sandboxing docs also say this is not a perfect boundary: it limits filesystem and process access, and the Gateway itself stays on the host.

Run a small business in the UK? We can name 3 admin jobs we could take off you, free and in writing. Get your free 3-job list

What our free check covers

We built a free paste check. Paste your openclaw security audit --deep output and openclaw --version. It puts the most important finding first, in plain English, with how to fix that one when we have steps for it. It also looks for risky settings, such as API keys handed to skills, and checks the version against published OpenClaw security advisories. Nothing is installed into the agent you're checking.

We check the text you paste. Your browser hides many common key and token formats before sending, but not all of them, so remove any other secrets first. Green means no issues found in the checks we ran. See Limits of the check.

The check is free, and a full report is $29. One-off $29, not a subscription. Refunded automatically if the check can't finish, or in full if you ask within 14 days. The full report explains every finding and lists the fixes in order. We don't review the code inside skills or MCP servers ourselves, beyond what OpenClaw's own audit reports.

Is My Agent Safe is independent and isn't affiliated with or endorsed by OpenClaw or its maintainers.

Written with AI assistance by the Is My Agent Safe team at Your Evenings Ltd.

Where next

Frequently asked questions

Is the OpenClaw sandbox on by default?

No. OpenClaw's sandboxing docs say sandboxing is off by default, under agents.defaults.sandbox.mode. Sessions whose creator role requires a sandbox still run sandboxed even when the agent mode is off.

What is the difference between non-main and all?

OpenClaw's mode docs say non-main sandboxes every session except the agent's main session. Group and channel sessions use their own keys, so they always count as non-main and get sandboxed. all sandboxes every session, including the main one.

Why didn't my sandbox config change take effect?

OpenClaw's sandbox CLI docs say updating sandbox config does not affect running containers. Existing runtimes keep their old settings, and regularly used agents can keep stale runtimes alive. Stop the Gateway, then run openclaw sandbox recreate --all so the next use rebuilds the runtime from the current config. Then run openclaw gateway restart.

Can Is My Agent Safe check this for me?

We built a free paste check. Paste your openclaw security audit --deep output and openclaw --version, and it puts the most important finding first, in plain English, with how to fix that one when we have steps for it. We don't review the code inside skills or MCP servers ourselves, beyond what OpenClaw's own audit reports.

Sources

  1. OpenClaw docs: sandboxing (checked 15 Nov 2026)
  2. OpenClaw docs: modes, scope and backend (checked 15 Nov 2026)
  3. OpenClaw docs: images and setup (checked 15 Nov 2026)
  4. OpenClaw docs: workspace access (checked 15 Nov 2026)
  5. OpenClaw docs: sandbox CLI (checked 15 Nov 2026)
  6. OpenClaw docs: sandbox vs tool policy vs elevated (checked 15 Nov 2026)
  7. OpenClaw docs: security audit checks (checked 15 Nov 2026)