How to Configure OpenClaw Sandboxing

Sandboxing in OpenClaw is about reducing blast radius, not pretending you have a perfect security boundary. The docs say the gateway stays on the host while tool execution can run inside a sandbox backend such as Docker, SSH, or OpenShell. That is a meaningful protection layer when the model is driving tools, especially if you are mixing coding, shell work, and browser automation.

When this is the right move

Use sandboxing when you want a stricter execution environment for tools, when non-main sessions should not share full host access, or when you need a remote execution boundary that still fits the OpenClaw tool model. It is especially valuable when the agent touches real files or shells and you want mistakes to be smaller.

The practical workflow

1. Decide when sandboxing should apply by choosing the documented mode: off, non-main, or all sessions.
2. Choose the scope that matches your risk and cost tradeoff: one sandbox per agent, per session, or one shared sandbox.
3. Pick a backend deliberately. Docker is the default local backend when sandboxing is enabled, while SSH and OpenShell are more explicit remote choices.
4. Set workspace access and any sandbox browser settings before you ask the agent to rely on the sandbox for real work.
5. Review every place where execution can still escape, especially elevated exec, so you do not assume more containment than you actually have.

Grounded command or config pattern

The docs include a concrete SSH backend example. It is a good reference because it shows the major sandbox knobs in one place.

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

The same docs note that Docker is the default backend when sandboxing is enabled and no backend is chosen. They also call out Docker-out-of-Docker path-mapping constraints when the gateway itself runs inside Docker and is orchestrating sibling sandbox containers from the host socket.

Operator notes

Sandboxing covers tool execution and an optional sandbox browser, but not the gateway process itself. Browser controls can be further tightened with network and CDP-related allowlists. Scope matters operationally too: per-session sandboxes are cleaner but more expensive than a shared one. The docs also remind you that group or channel sessions count as non-main when mode is non-main, which is easy to overlook if you assumed only subagents were getting boxed in.

Rollout approach

For OpenClaw sandboxing, I would prove the smallest useful isolation story first: pick one backend, one mode, and one harmless command in a sandboxed session. Once you can explain exactly where the files and processes ran, you can widen usage. If you cannot explain the boundary, you do not really have one yet.

Common mistake

The common mistake is treating the command or config key as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and one small verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A short note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or host changes.

Safety checks

Do not sell yourself a false security story. The docs plainly say sandboxing is optional and imperfect, and elevated exec bypasses it. If you need a stronger trust boundary, design for that explicitly. Also be careful with host path mapping and workspace access so you do not accidentally give the sandbox more host visibility than you intended.

How to verify it worked

Run one harmless file read or exec in a sandboxed session and confirm the action lands in the expected sandbox workspace or remote host. If you are using a sandboxed browser, make sure the browser actually comes up through the sandbox path instead of quietly targeting the host. Verification here should be literal, not assumed.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.