OpenClaw Sandboxing Explained

Sandboxing is the difference between “the agent starts in this folder” and “the agent is actually constrained.” OpenClaw is candid about that distinction, and I appreciate it. Too many tools blur convenience and isolation until operators believe they are protected when they are really just standing in a polite default directory.

Default to the smaller surface area

The sandboxing docs focus on exactly what gets sandboxed, which modes exist, what scope means, and which backend is doing the real work. That clarity matters because different backends imply different trust assumptions. Docker, SSH, and OpenShell are all valid routes, but they are not interchangeable. You should choose the backend that matches your environment, data sensitivity, and operational comfort rather than picking at random because a keyword sounded familiar.

That default is a recurring OpenClaw theme. The platform usually gives you a convenient path and a safer path, and the docs are pretty clear that the safer path should win unless you genuinely need something broader. If you treat every network, auth, and execution option as interchangeable, you will create problems that look like product bugs but are really trust-boundary mistakes.

Documented setup pattern

The documented config examples show how to define sandbox mode, backend, scope, workspace access, and backend-specific details such as SSH targets or Docker binds. That is the right level of explicitness. You can look at a config and tell what the execution boundary is supposed to be. When teams skip that precision, they usually end up debating symptoms instead of seeing that the sandbox design itself was underspecified from day one.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
        },
      },
    },
  },
}

• Choose the backend based on your trust boundary, not just familiarity with the technology.
• Set scope and workspaceAccess deliberately so the sandbox matches the risk of the work.
• Use Docker binds or SSH workspace roots to make the file boundary explicit.
• Do not confuse “default cwd” with true isolation.

Checks before you call it done

Operationally, the clean move is to decide which jobs genuinely require enforced isolation and then make that requirement visible in the agent or child-session configuration. The docs also note that sandboxed sessions are clamped to a narrower session-tool visibility level, which is exactly the kind of cascading safety effect you want. Once a run is sandboxed, other powerful surfaces should narrow with it rather than quietly remaining broad.

The main mistake is assuming all sandbox backends buy the same guarantees. They do not. Another is turning on sandboxing without thinking about workspace access or required mounts, then interpreting expected access failures as mysterious bugs. The docs give you enough structure to avoid both. Sandboxing works best when you design the boundary before you need the job to succeed quickly.

A sandbox is only helpful when its limits are real and legible. OpenClaw gives you the pieces to do that properly. If you want the practical operator layer on top of the official docs, The OpenClaw Playbook turns setups like this into real workflows, guardrails, and day-to-day patterns you can actually run.

I would also keep the backend choice tied to the actual workflow. Remote build execution over SSH, reproducible runs in Docker, and OpenShell-local isolation each solve different problems. “Use sandboxing” is not the full decision. “Use the right sandboxing shape for this risk” is.

Use the official docs as the source of truth, keep the workflow explicit, and tighten the scope before you automate more than you can comfortably review.