OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

Sandboxing

Status: active

OpenClaw can run tool execution inside a sandbox backend to reduce blast radius. Sandboxing is off by default and controlled by agents.defaults.sandbox (global), agents.entries.*.sandbox (per-agent), or a required creator-role sandbox policy. The Gateway process always stays on the host; only tool execution moves into the sandbox when enabled.

Sandboxing pages

This page is an index. The sandbox reference is documented on eleven pages. Open the page that matches what you are configuring.

Page Read it when
What gets sandboxed You want to know exactly which execution moves into the sandbox.
Modes, scope, and backend You are deciding which sessions run sandboxed and how they share environments.
Supported capability matrix You are comparing Docker, SSH, and OpenShell before choosing a backend.
Docker backend You are running the default local backend or enabling the sandboxed browser.
Podman backend You are using Podman instead of Docker for sandboxed tool execution.
SSH backend You are offloading sandboxed tool execution to a remote machine over SSH.
OpenShell backend You are sandboxing tools in an OpenShell-managed remote environment.
Workspace access You are deciding what the sandbox can see of the agent workspace.
Multiple folders for one agent One sandboxed agent needs more than its primary workspace.
Images and setup You need to build or customize a sandbox image.
setupCommand (one-time container setup) You need to run one-time setup inside a newly created sandbox container.

Where each section moved

Every anchor this page used to publish is kept here, so an existing link such as /gateway/sandboxing#images-and-setup still resolves. Each entry points at the page that now holds the content.

Tool policy and escape hatches

Tool allow/deny policies still apply before sandbox rules. If a tool is denied globally or per-agent, sandboxing doesn't bring it back.

tools.elevated is an explicit escape hatch that runs exec outside the sandbox (gateway by default, or node when the exec target is node). /exec directives only apply for authorized senders and persist per session; to hard-disable exec, use tool policy deny (see Sandbox vs Tool Policy vs Elevated).

Debugging:

  • openclaw sandbox list shows sandbox containers, status, image match, age, idle time, and associated session/agent.
  • openclaw sandbox explain [--session <key>] [--agent <id>] inspects effective sandbox mode, host workspace, runtime workdir, Docker mounts, tool policy, and fix-it config keys. Its workspaceRoot field remains the configured sandbox root; effectiveHostWorkspaceRoot shows where the active workspace actually lives.
  • openclaw sandbox recreate [--all | --session <key> | --agent <id>] [--browser] [--force] removes containers/environments so they get recreated with current config on next use.
  • See Sandbox vs Tool Policy vs Elevated for the "why is this blocked?" mental model.

Multi-agent overrides

Each agent can override sandbox + tools: agents.entries.*.sandbox and agents.entries.*.tools (plus agents.entries.*.tools.sandbox.tools for sandbox tool policy). See Multi-Agent Sandbox & Tools for precedence.

Minimal enable example

json5
{  agents: {    defaults: {      sandbox: {        mode: "non-main",        scope: "session",        workspaceAccess: "none",      },    },  },}
Was this useful?
On this page

On this page