OpenClawDocs
On this page

On this page

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 limit the damage tools can cause. 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 twelve 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.
Crabbox backend You want tool execution on a Crabbox-leased cloud box while the agent stays local.
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.

Managed GitHub identity

Sandboxed execution excludes the agent's managed GitHub identity by default. Set agents.entries.<id>.tools.github.allowInSandbox: true on that agent's managed identity to allow it inside the agent's own Docker or Podman sandbox. OpenClaw mounts the selected profile read-only at /openclaw/github, sets GH_CONFIG_DIR to that path, and provides the same managed token and Git author as host execution. The container needs gh installed for GitHub CLI commands.

This opt-in exposes credentials to code running in the sandbox; read-only mounting prevents profile edits, not credential reads. openclaw security audit emits a warning for every opted-in agent. Effective scope: "shared" refuses identity injection and logs a warning naming the agent, because that container can serve other agents. Role-required sandboxes retain their per-creator isolation and support the opt-in. Other sandbox backends reject provisioning with the opt-in enabled. See GitHub identity.

Minimal enable example

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