skip to content

Sandboxing & Tool Policy

Sandbox modes run risky sessions in Docker, tool policy allows or denies tools, and exec approvals gate shell commands. Interviewers ask how these layers stop injected instructions.

part ofAI coding toolsread it →
on this pageshow

explore

questions

6

Does OpenClaw run an agent's tools in a sandbox by default, and what moves into the sandbox once you turn it on?

level: juniorimportance: must knowfreq 14%

answer

  1. opt-in, not on by default
  2. agents.defaults.sandbox.mode
  3. tools move, the daemon stays
  4. default container: no network
  5. workspaceAccess starts at none

basics

~20 s

No. OpenClaw sandboxing is off by default, so tools run on the Gateway host. When you enable it, only tool execution (shell, file tools, the optional browser) moves into a container; the Gateway process itself always stays on the host.

solid answer

~40 s

Sandboxing is **opt-in**: `agents.defaults.sandbox.mode` defaults to `off`, so on a fresh install `exec`, `read`, `write` and friends run directly on the Gateway host. Setting the mode to `non-main` or `all` (globally or per agent under `agents.entries.<id>.sandbox`) moves **tool execution** into a sandbox backend, Docker by default. The Gateway daemon never moves: it keeps the channel connections, config and credentials on the host. The default Docker sandbox runs with `network: "none"`, a read-only root filesystem and all capabilities dropped, and `workspaceAccess` defaults to `none`, so tools see an isolated workspace under `~/.openclaw/sandboxes` rather than your agent workspace. Tool allow/deny policy still applies first; a sandbox never brings back a denied tool. The docs call it a material limit on filesystem and process access, not a perfect security boundary.

go deeper

for a junior

Remember the default: sandboxing is off, so tools run on the Gateway host. Turning it on moves tool execution, not the Gateway.

for a middle

Explain the knobs: mode off, non-main or all; scope agent, session or shared; workspaceAccess none, ro or rw; and the default Docker container with no network.

for a senior

Show you verify rather than assume: read openclaw sandbox explain, recreate containers after config changes, and audit bind mounts that pierce the container.

for a principal

Frame the sandbox as one damage-limiting layer whose cost is container upkeep and lost convenience, and decide which agents justify it next to tool policy and approvals.

## The default: nothing is sandboxed OpenClaw is a self-hosted assistant: one long-running **Gateway** process holds your chat connections (WhatsApp, Telegram, Discord and so on), reads `~/.openclaw/openclaw.json`, and runs agent turns. During a turn the model calls **tools** such as `exec` (shell commands), `read`, `write`, `edit` and `apply_patch`. Out of the box those tools run **directly on the machine that hosts the Gateway**. The setting that changes this is `agents.defaults.sandbox.mode`, and its default is `off`. The exec tool's own `host` parameter defaults to `auto`, which resolves to `sandbox` only when a sandbox runtime is active and to `gateway` otherwise, so with no sandbox configured a shell command lands on the host. An explicit `host=sandbox` with no sandbox does not silently fall back: it fails closed. The practical meaning: until you opt in, whatever the model is talked into running runs as the operating-system user that runs OpenClaw. ## What moves and what stays | Part | With sandboxing enabled | | --- | --- | | `exec`, `process`, `ls`, `read`, `write`, `edit`, `apply_patch` | Run inside the sandbox backend | | The optional sandboxed browser (`agents.defaults.sandbox.browser`) | Runs in its own container | | The **Gateway process** | Always stays on the host | | `exec` with elevated mode allowed | Escapes to the configured host path | Keeping the Gateway on the host is deliberate: it owns the messaging sessions, configuration and credentials, and only the risky part, tool execution, needs a smaller blast radius. Running the *whole* Gateway inside Docker is a separate deployment choice with a different boundary. ## Turning it on 1. Pick a **mode**: `off`, `non-main` (everything except the agent's main session) or `all` (every session). 2. Pick a **scope**: `agent` (default, one container per agent), `session` (one per session) or `shared` (one for all sandboxed sessions). 3. Pick a **backend**: `docker` is the default; `podman`, `ssh`, `openshell` and `crabbox` also exist. 4. Decide `workspaceAccess`: `none`, `ro` or `rw`. The minimal example the documentation ships is mode `non-main`, scope `session`, `workspaceAccess: "none"` under `agents.defaults.sandbox`. Per-agent overrides go under `agents.entries.<id>.sandbox`. ## What the default Docker sandbox looks like - **No network**: `docker.network` defaults to `"none"`, so a command cannot reach the internet unless you open it. - **Read-only root filesystem** (`readOnlyRoot: true`) and **all Linux capabilities dropped** (`capDrop: ["ALL"]`). - Image `openclaw-sandbox:bookworm-slim`, which runs as a non-root user and does not include Node. - `workspaceAccess: "none"`: tools read and write an isolated sandbox workspace under `~/.openclaw/sandboxes`; your real agent workspace is not mounted. `ro` mounts it read-only at `/agent`; `rw` mounts it read-write at `/workspace`. - Bind mounts you add with `docker.binds` pierce that isolation. They are validated against a blocked-path list that covers system paths, the Docker socket and home credential folders such as `.ssh` and `.aws`. ## Checking and changing it - `openclaw sandbox explain` prints the effective mode, scope, workspace access, sandbox tool policy and the config keys that would change them. - `openclaw sandbox list` shows running sandbox containers with their image match and idle time. - Editing sandbox config does **not** reconfigure containers that already exist. Idle ones are pruned after `prune.idleHours` (24 by default), but a busy agent can keep a stale container alive, so run `openclaw sandbox recreate --all` after a change. ## Where it stops - **Tool policy comes first.** If `tools.deny` removes a tool, enabling the sandbox does not bring it back. - **It limits damage; it does not decide intent.** A sandboxed `exec` can still do anything the container allows, which is why tool policy and exec approvals sit beside it. - **Elevated mode** is an explicit hatch that lets allowed senders run `exec` outside the sandbox; with sandboxing off it changes nothing, because exec is already on the host. - The documentation itself says the sandbox is not a perfect security boundary; it materially reduces filesystem and process access when the model does something it should not.

  • I changed agents.defaults.sandbox.docker.network; why does the agent still behave the old way?
    Existing sandbox runtimes keep the settings they were created with. Idle containers are pruned after `prune.idleHours` (24 by default), but an agent in regular use can keep a stale one alive. Run `openclaw sandbox recreate --all` (or `--agent <id>`) so the next use rebuilds the container from current config.
  • Is running the whole OpenClaw Gateway in Docker the same as enabling the tool sandbox?
    No. The docs treat them as complementary. A Gateway container puts one boundary around everything, including the daemon. The tool sandbox (`agents.defaults.sandbox`) keeps the Gateway on the host and isolates tool execution per agent or session, with its own network, workspace-access and tool-policy controls.

  • A fresh OpenClaw install runs every tool call inside Docker.
  • Enabling the sandbox moves the whole Gateway process into a container.
  • Turning on the sandbox brings back tools that tool policy denied.
  • The default sandbox container has internet access and sees the agent workspace.
  • Editing sandbox config instantly reconfigures containers that are already running.
open as a page

In OpenClaw, how do tools.allow and tools.deny decide which tools an agent can call, and what do they not control?

level: middleimportance: must knowfreq 10%

basics

~20 s

OpenClaw tool policy filters tools by name: deny always wins, and a non-empty allow blocks everything not listed. It applies with or without the sandbox and is the hard stop, but it does not inspect what an allowed exec command does.

open as a page

On an OpenClaw Gateway host, how do exec approvals decide whether a shell command runs, and what does a fresh install do?

level: middleimportance: should knowfreq 8%

basics

~20 s

As of OpenClaw 2026.9.9, host exec defaults to security full and ask off, so commands run without a prompt. With an allowlist and ask on-miss, unmatched commands wait for approval, and if no approver is reachable, askFallback (default deny) blocks them.

open as a page

A group-chat message tells an OpenClaw agent to run a shell command and print the owner's SSH keys; how do tool policy, the sandbox and elevated mode each stop it?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Tool policy decides first: if exec is denied, nothing runs. If exec is allowed, the sandbox decides where it runs; a sandboxed group session sees no host home directory. Elevated could send exec to the host, but only for senders in tools.elevated.allowFrom.

open as a page

With OpenClaw's agents.defaults.sandbox.mode set to non-main, which sessions still run tools on the host, and why can that surprise an operator?

level: seniorimportance: should knowfreq 6%

basics

~20 s

Only the agent's main session (agent:<agentId>:main) stays on the host; group and channel sessions have their own keys and are sandboxed. Under the default session.dmScope of main, direct messages share that main session, so they run on the host too.

open as a page

What sandbox and tool-policy baseline would you set for an OpenClaw agent that answers strangers in public groups, and what risk does it still leave?

level: principalimportance: nice to knowfreq 5%

basics

~20 s

Give public traffic its own agent: sandbox mode all, workspaceAccess none, no network, a deny list covering shell, file, automation and delegation tools, and elevated off. One Gateway is still one trust boundary, so messaging and session reach remain the residual risk.

open as a page