Security

Before you enable an OpenClaw tool, read the sandbox explain output

June 12, 202613 min readUpdated September 13, 2026By OpenClawBlog Team

Published June 12, 2026 · OpenClawBlog Team

A tool can have a small description and a large reach. “Read a report” may involve filesystem access, a shell, a plugin, a browser session, or a network request. Before enabling it, you need to know what the active OpenClaw session can actually reach.

OpenClaw’s sandbox inspector is built for that question. openclaw sandbox explain reports the effective sandbox mode, scope, workspace access, tool policy, and elevated gates. It also exposes the paths and runtime details that are easy to miss in a configuration file. Read the output as a boundary map. It can show what the session is configured to do; it does not certify the tool, the container, or the host.

Inspect the exact session first

Run the report for the agent or session that will receive the tool:

openclaw sandbox explain --session agent:main:main --json
openclaw sandbox explain --agent work --json

The CLI accepts a session key, an agent identifier, or a normal human-readable session name. The choice matters. A report for work does not describe the environment of main, and a report for a local session may not describe a group or channel session. In a multi-agent setup, use an explicit --agent when there is no implicit owner.

Keep the report with the approval record. Record the agent or session, the OpenClaw version, the time of inspection, and the tool being considered. The JSON form is easier to compare after a configuration change, but it can reveal private paths and policy choices, so treat it as internal operational data.

Read mode as a routing result

The first decision is whether the target session is sandboxed at all. OpenClaw’s current sandbox reference documents three modes:

off leaves sessions on the host unless a creator role requires sandboxing;
non-main sandboxes every session except the agent’s main session;
all sandboxes every session.

The default mode is currently documented as off. A separate operator-role policy can require a sandbox for newly created sessions, and that requirement takes precedence over the agent mode. If the required backend cannot be provisioned, the session fails closed instead of silently moving to the host.

This is where many approvals go wrong. An operator sees that sandboxing is configured somewhere and assumes the tool will be isolated. The report should answer a narrower question: will this exact turn run inside the sandbox? If the answer is no, do not approve a sensitive tool on the assumption that another session’s settings will protect it.

Scope and backend tell you what is shared

Mode says when isolation applies. Scope says how much environment is shared. The documented values are agent, session, and shared. Agent scope uses one environment per agent. Session scope separates sessions. Shared scope uses one environment for all sandboxed sessions and can ignore some per-agent Docker, SSH, or browser overrides.

That changes the recovery question. A session-scoped environment is easier to discard without affecting another session. An agent-scoped environment may retain files between tasks for the same agent. A shared environment means that a file or installed package created by one sandboxed session may be available to another. The report does not make those choices good or bad; it makes them visible.

Check the backend as well. Docker and Podman run locally. SSH runs tools on an SSH-accessible host. OpenShell uses its own managed policy. The capability matrix documents different network and workspace behavior for each backend. “Sandboxed” is not a complete description of where the code runs.

Workspace access is the data boundary

The workspaceAccess line is usually the most useful part of the report for a file-handling tool. OpenClaw documents three values:

Value	What the sandbox can see	Operator question
`none`	An isolated sandbox workspace; the agent workspace is not exposed.	Where will the tool get its input, and where will its output remain?
`ro`	The agent workspace is mounted read only at `/agent`; direct write, edit, and patch tools are disabled.	Is read access enough, and is the result written somewhere separately?
`rw`	The agent workspace is mounted read and write at `/workspace`.	Which files may change, and who will review or restore them?

Do not confuse the configured sandbox root with the host workspace that is actually active. The CLI documentation says the report keeps workspaceRoot as the configured sandbox root and separately shows effectiveHostWorkspaceRoot. Those values answer different questions. One describes the isolation area; the other identifies the host-backed workspace involved in the current session.

There is a further limit for role-required sandboxes. OpenClaw can cap a configured read-write workspace at read only and log a sandbox warning. Read the effective result and the warning, not only the desired configuration. Skills may also be mirrored into sandbox-readable paths, which does not mean that the rest of the private workspace is visible.

Inspect mounts after reading workspaceAccess

A narrow workspace setting can be widened by explicit Docker binds. OpenClaw’s sandbox and tool-policy reference says that anything in docker.binds is visible inside the container with the selected mode. If the mode is omitted, the documented default is read and write. A read-only source mount and a read-write project mount are different approvals.

Look for every mount in the report. Ask why the host path exists, whether it is read only, and whether it contains credentials, browser state, unrelated repositories, or generated files. A report that says workspaceAccess: none but lists a broad read-write bind is not practically a no-workspace configuration.

Pay special attention to /var/run/docker.sock. The documentation describes binding it as effectively handing host control to the sandbox. That is not a normal convenience mount. If it appears, stop and treat the proposed tool as a host-administration tool regardless of its name.

Tool policy answers availability, not side effects

The report also shows the effective sandbox tool allow and deny rules and where those rules came from. OpenClaw resolves several layers: tool profiles, provider profiles, global and per-agent policy, provider policy, and sandbox-specific policy. A deny wins, and a non-empty allowlist blocks tools outside it.

This helps explain a blocked tool, but it should not be mistaken for a side-effect analysis. Tool policy filters by tool name. If exec is allowed, denying write, edit, or apply_patch does not make shell commands read only. A shell can still modify files through commands. For a read-only workflow, deny runtime execution as well as the mutating file tools unless another operating-system boundary enforces the restriction.

Conversely, sandboxing does not restore a tool that normal policy has denied. If a tool is missing, check the global, agent, provider, and sandbox policies before weakening the sandbox. The report should tell you which rule needs review, and the Gateway logs can provide the related policy entry.

Check what remains on the host

OpenClaw’s sandbox scope documentation is explicit about the boundary. Tool execution such as exec, read, write, edit, and process can run inside the sandbox. The Gateway process itself does not move there.

Native plugins and MCP tools also deserve separate attention. The capability matrix says plugin and MCP access remains Gateway-side and is additionally gated by normal policy and sandbox tool policy. A plugin that runs in the Gateway process is not made safe merely because the requesting session has a container.

Then read the elevated section. Elevated mode is an exec-only escape path from ordinary sandboxing. Its enablement and sender allowlists appear as gates in the report. If it is allowed, an otherwise sandboxed command may run outside the sandbox. A creator role that requires sandboxing cannot be bypassed through elevated execution, but a normal sandboxed session may have this path available. If the tool does not need host execution, keep the path disabled.

Network access depends on the backend

For Docker, the current capability matrix documents docker.network and says its default is none. SSH network behavior depends on the remote host. OpenShell behavior depends on the selected OpenShell policy. Read the backend line before interpreting the network result.

A tool that reads private files and can contact arbitrary external hosts has a larger failure radius than a tool that transforms local files without network access. If network access is required, name the service, the credential scope, and the expected direction of traffic. If the report does not make those limits visible, reduce the data exposed to the tool or defer approval.

Do not use a Docker network result as a statement about every OpenClaw action. The Gateway and in-process plugins remain outside the container boundary. The report helps you identify that distinction; it does not inspect the business behavior of every plugin or external service.

Configuration changes may leave an old runtime active

There is a maintenance trap in the CLI documentation. Changing sandbox configuration does not update an already-running container. Existing runtimes keep their old settings until they are recreated.

If you change the image, mode, workspace access, bind list, SSH target, or setup command, use the documented recreation path:

openclaw sandbox recreate --agent work
openclaw sandbox explain --agent work --json
openclaw sandbox list --json

Choose the narrowest scope that covers the change. The CLI reference warns that recreating SSH or remote OpenShell environments can delete the canonical remote workspace for the selected scope before the next run seeds it again. Understand that consequence and preserve any required data before recreating a remote environment.

A report captured before the change and a report captured after the change are not enough if the active runtime was never rebuilt. The approval record should say whether the runtime was recreated and whether the mount and backend details were checked afterward.

Use stop conditions instead of a green light

Finding	What it means	Decision
Target session is not sandboxed	The tool runs with host execution authority unless another policy applies.	Defer a sensitive tool or explicitly approve the host boundary.
Workspace is read and write	The agent workspace can be changed.	Use a disposable workspace or narrow the mount.
Unexpected read-write bind	A host path widens visibility beyond the workspace setting.	Remove it, change it to read only, or document why it is required.
`exec` is allowed for a read-only job	Shell commands may still mutate files.	Deny runtime execution or use a separate enforced boundary.
Elevated gates are open	Exec may have a host escape path.	Keep the tool out until the gate and sender scope are justified.
Backend network policy is unclear	The report does not establish the external data path.	Inspect the backend policy or remove private inputs.
Configuration changed but runtime is old	The active container may still use previous mounts or settings.	Recreate, then capture a fresh report.

Test the boundary that matters

The report should lead to a small, reversible test. Use a disposable workspace with synthetic files. Ask the tool to perform its intended harmless operation. Then test the edges separately: read a sentinel file outside the permitted path, write outside the expected output directory, and make a network request that the task does not need. Decide the expected result before running each test.

Save the report, the test inputs, and the observed results together. If an outside read or write succeeds, stop. If a network request succeeds when the selected policy should deny it, stop. If the result is ambiguous because the tool used a Gateway-side plugin or a remote backend, mark the boundary unverified rather than calling the test a pass.

This is an operator test proposal, not a claim that OpenClaw has been tested on a particular machine. It is also not a replacement for reviewing the tool’s source, dependencies, credentials, or external side effects.

What the report cannot prove

OpenClaw’s security documentation describes sandboxing as a way to reduce blast radius, not a perfect security boundary. The report cannot prove that the tool’s implementation matches its description. It cannot prove that an installed dependency is trustworthy, that untrusted content will not influence the model, or that a plugin will not perform an external action through the Gateway.

The project’s security policy also frames one Gateway as one trusted boundary. Session ownership and visibility are not substitutes for isolation between mutually adversarial operators. If the tool will serve people who do not trust one another, separate the Gateway, credentials, and preferably the operating-system host.

The approval rule

Enable the tool when the exact target session is sandboxed as intended, the effective workspace is no broader than the task requires, mounts are understood, tool policy matches the operation, elevated access is closed unless justified, the backend’s network behavior is known, and the runtime is current. A disposable negative test should support those conclusions.

If one of those answers is unknown, the sensible result is not a forced approval. Reduce the data, narrow the tool, rebuild the runtime, or keep the tool in a restricted pilot. The value of openclaw sandbox explain is that it turns a vague feeling of isolation into a list of decisions an operator can record and revisit.

Sources

Sources accessed 2026-09-13. The documentation and repository pages did not state publication dates, so the publication field is left empty in the source record.