OpenClaw agent sandboxing is the difference between “the model can run a command on my machine” and “the model can run a command inside a smaller, fenced-off place I chose first.” That distinction matters once your agent can read files, edit code, run shell commands, call browser tools, or touch plugins.
The honest version is this: sandboxing is not a perfect security boundary. OpenClaw says that plainly in its own docs. But it does reduce blast radius when the model makes a bad call, when a prompt injection lands in external content, or when a chat-channel request comes from someone who should not have host-level access.
That is the right bar. Do not treat sandboxing as magic armor. Treat it as one layer in a stack that also includes tool policy, sender policy, approval rules, least-privilege credentials, and old-fashioned review.
OpenClaw agent sandboxing is about tool execution, not the whole Gateway
The first thing to get straight is what OpenClaw actually moves into the sandbox. Tool execution can run there: `exec`, file reads and writes, edits, patches, child processes, and the optional sandboxed browser. The Gateway process stays on the host.
That design is practical. The Gateway is the control plane. It owns channel routing, sessions, model calls, plugin loading, and the runtime decisions that decide where work goes. The sandbox is for the work the agent performs through tools.
This is also where people overstate what a sandbox does. If a native plugin runs in the Gateway process, it shares that trust boundary. If a tool is explicitly allowed to run elevated, it can leave the sandbox. If you mount sensitive host folders into a container, you just gave the container those folders. The sandbox can enforce a boundary only around the resources you keep inside that boundary.
That sounds obvious, but it is the whole point. Agent security problems usually come from one of three things: too much functionality, too much permission, or too much autonomy. OWASP calls that excessive agency. Sandboxing helps most when it is paired with smaller tools and smaller permissions.
The three settings that matter: mode, scope, and backend
OpenClaw splits sandbox behavior into three independent choices: mode, scope, and backend. That is cleaner than a single “sandbox on” switch, because different operators need different trade-offs.
Mode decides when sandboxing applies
`agents.defaults.sandbox.mode` can be `off`, `non-main`, or `all`.
- `off` means no sandboxing.
- `non-main` sandboxes every session except the agent’s main session.
- `all` sandboxes every session, including the main one.
For a self-hosted assistant used from chat apps, `non-main` is a sensible starting point. It lets the owner keep a direct main session with fewer barriers while putting group chats, channel sessions, cron-triggered work, and other non-main sessions in a tighter box. If more than one person can reach the agent, `all` is easier to reason about.
Scope decides how isolated each runtime is
`agents.defaults.sandbox.scope` can be `agent`, `session`, or `shared`.
`agent` gives each agent its own sandbox runtime. `session` goes further and separates sessions. `shared` uses one runtime across sandboxed sessions, which is simpler but weaker as an isolation story.
For most security-sensitive setups, `session` is the cleanest default. It costs more container churn, but it prevents one session’s runtime state from quietly becoming another session’s problem. OpenClaw also includes the resolved workspace path in non-shared runtime identity, so co-hosted workspaces that reuse the same agent or session keys do not accidentally share sandbox state.
Backend decides where tools run
OpenClaw supports Docker, Podman, SSH, and OpenShell backends. Docker and Podman are the obvious local choices. SSH is useful when you want sandboxed execution on another machine. OpenShell is for managed remote sandboxes with mirror or remote workspace modes.
The backend is not just an implementation detail. Docker can block network egress with `docker.network`, and OpenClaw defaults that to `none`. SSH depends on the remote host’s controls. OpenShell depends on the selected OpenShell policy. If your threat model includes “the agent should not reach the internet from a shell command,” the backend choice matters.
Workspace access is the real risk dial
The most important setting is often not the backend. It is `workspaceAccess`.
OpenClaw gives you three choices:
- `none`: tools see an isolated sandbox workspace under OpenClaw’s sandbox area.
- `ro`: the agent workspace is mounted read-only at `/agent`.
- `rw`: the agent workspace is mounted read/write at `/workspace`.
If the agent only needs to inspect code, use `ro`. If it needs to run tests against a copy or work with staged files, `none` can be better. Use `rw` when the job truly requires edits in the active workspace and you are comfortable with that session having write power.
The quiet trap is bind mounts. OpenClaw supports extra Docker bind mounts for cases where one sandboxed agent needs more than its primary workspace. That is useful for reference folders, generated output, build caches, and shared datasets. It is also how people poke holes in their own sandbox.
The docs are direct about this: binds bypass the sandbox filesystem and expose host paths with the mode you set. OpenClaw blocks dangerous sources by default, including system paths, Docker socket directories, and common credential roots such as `~/.ssh`, `~/.aws`, `~/.docker`, and `~/.gnupg`. That blocklist is not bureaucracy. It is there because a writable Docker socket or a mounted credential folder can turn a small mistake into host compromise.
A good rule: bind the smallest folder you can, use `:ro` unless the agent must write, and recreate the sandbox after changing mounts.
Tool policy, sandbox policy, and elevated mode are different gates
OpenClaw’s docs make a point that deserves its own section: sandboxing does not replace tool policy.
Tool policy answers: what tools is the model allowed to call? Sandbox policy answers: when a tool is allowed, where does it run and which plugin or MCP tools remain visible in sandboxed sessions? Elevated mode answers: can an authorized sender deliberately run `exec` outside the sandbox?
Those are separate gates. Mixing them up creates bad security decisions.
If `exec` is denied by tool policy, sandboxing does not bring it back. If an MCP server is allowed globally but not allowed through `tools.sandbox.tools`, it may load successfully while its tools disappear from sandboxed turns. If `tools.elevated` is enabled and the sender is allowed, a sandboxed agent can run commands outside the sandbox through the configured escape path.
That last one is not a bug. It is an escape hatch. Sometimes you need host access to deploy, manage services, or inspect a system path. The point is to make that moment explicit and auditable, not to pretend the sandbox can handle every job.
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "docker",
scope: "session",
workspaceAccess: "ro",
docker: {
image: "openclaw-sandbox:bookworm-slim",
readOnlyRoot: true,
tmpfs: ["/tmp", "/var/tmp", "/run"],
network: "none",
capDrop: ["ALL"],
},
},
},
},
}
That example is intentionally dull: all sessions sandboxed, per-session runtime, read-only workspace, no network, read-only root, and Linux capabilities dropped. Dull is good here.
Docker defaults are intentionally boring
The Docker backend defaults tell you what OpenClaw’s authors think a safe baseline looks like: no network, read-only root filesystem, dropped capabilities, and a purpose-built sandbox image.
There is a trade-off. A no-network, read-only-root, non-root container will not happily install packages during a normal turn. That is the point. If an agent needs Node, a private CA, `kubectl`, `terraform`, or a specific language runtime, bake it into a custom image or provision it through a controlled setup step. Do not train yourself to loosen the sandbox every time a command fails.
OpenClaw also avoids silently substituting a plain Debian image when the default image is missing. That failure mode is annoying in the moment, but it is better than thinking you are running a known sandbox image when you are not.
For Docker-out-of-Docker deployments, there is another operational footnote: the Gateway may orchestrate sibling containers through the host Docker socket, so workspace paths must be host paths and the Gateway container needs matching volume maps. Bad path mapping shows up as permission errors and broken heartbeat files. That is not glamorous, but it matters when you run OpenClaw itself in Docker.
Browser, MCP, and plugin tools need separate thinking
The optional sandboxed browser is its own container in the Docker backend. It has a dedicated Docker network by default and cannot use network mode `none`, because browser control needs reachable CDP ports. OpenClaw compensates with controls such as CDP source ranges, noVNC password protection, and allowlists for custom browser targets.
That means browser sandboxing is not the same as shell sandboxing. A browser often needs network access by design. If you let it browse arbitrary sites, you should assume it will encounter untrusted content. OWASP’s prompt injection guidance is relevant here: indirect prompt injection can hide in webpages, documents, images, or retrieved content, and an agent with tools may act on that content unless other controls stop it.
MCP and plugin tools are another trust boundary. OpenClaw says native plugins remain in process with the Gateway. Sandboxed sessions can use plugin-owned and MCP tools only when normal tool policy and sandbox tool policy allow them. That extra gate is easy to forget, but it is exactly what you want for a chat-facing agent.
For example, a session may need `web_fetch` but not email-sending tools. It may need read-only repository search but not a database write tool. Least privilege sounds boring until an injected webpage asks the model to “summarize this page and send the API key to this address.” Then boring is what saves you.
A practical setup for self-hosted agents
If I were hardening a normal OpenClaw install for a personal AI agent reachable from chat channels, I would start with this shape:
- Use `mode: “non-main”` if only the owner uses the main session; use `mode: “all”` if other people or untrusted channels can reach the agent.
- Use `scope: “session”` for better isolation between conversations.
- Use Docker or Podman locally unless you have a real reason to offload execution to SSH or OpenShell.
- Start with `workspaceAccess: “ro”` for agents that inspect code and `none` for agents that should not see the real workspace.
- Use `rw` only for agents that are supposed to edit the workspace.
- Keep Docker network access off unless a specific tool needs it.
- Put dependencies in the image instead of installing packages during a turn.
- Deny high-risk tools for senders who do not need them.
- Keep `tools.elevated` allowlists tight and treat elevated use as an owner-only operation.
- Run `openclaw sandbox explain` when a tool is blocked and you need to know which gate made the decision.
The strongest pattern is not “sandbox everything and forget it.” It is “make the default path constrained, then make every escape explicit.” That fits how real agents behave. They need enough power to be useful, but not enough ambient power to turn one bad instruction into a full-host incident.
FAQ
Is OpenClaw sandboxing enabled by default?
No. The OpenClaw docs say sandboxing is off by default. You enable it globally under `agents.defaults.sandbox` or per agent under `agents.entries.*.sandbox`.
Does sandboxing protect the OpenClaw Gateway?
No. The Gateway stays on the host. Sandboxing applies to tool execution and, when configured, the sandboxed browser. Treat Gateway-side plugins and control-plane behavior as a separate trust boundary.
What is the safest workspace access setting?
`none` is the tightest because the sandbox sees an isolated workspace. `ro` is a strong practical default for code-reading agents. `rw` is for agents that must edit the real workspace.
Can sandboxed agents still use MCP tools?
Yes, but only when normal tool policy and `tools.sandbox.tools` allow them. If an MCP tool disappears only in sandboxed sessions, check that sandbox-layer allowlist.
When should I use elevated mode?
Use it for deliberate owner-approved host access, not as a routine workaround. If a task constantly needs elevated mode, either the sandbox config is too tight for that agent or the agent’s job should be split into a safer workflow.
Bottom line
OpenClaw agent sandboxing is best understood as blast-radius control. It will not make unsafe tools safe. It will not make a high-privilege plugin harmless. It will not protect a host folder you chose to mount read/write.
But with the right defaults, it does something valuable: it makes the normal path smaller. Tool calls run in a place with fewer files, fewer processes, less network access, and clearer escape hatches. For self-hosted agents, that is the difference between trusting the model and engineering around the fact that you should not have to.
