Does OpenClaw run an agent's tools in a sandbox by default, and what moves into the sandbox once you turn it on?
answer
- opt-in, not on by default
- agents.defaults.sandbox.mode
- tools move, the daemon stays
- default container: no network
- workspaceAccess starts at none
basics
~20 sNo. 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 sSandboxing 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
Remember the default: sandboxing is off, so tools run on the Gateway host. Turning it on moves tool execution, not the Gateway.
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.
Show you verify rather than assume: read openclaw sandbox explain, recreate containers after config changes, and audit bind mounts that pierce the container.
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.