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

Docker backend

The default local backend: its restricted defaults, GPU and Docker-out-of-Docker constraints, and the sandboxed browser container.

Docker backend

The Docker backend runs tools locally through the docker CLI. Its selection and error behavior are unchanged; it does not check or fall back to Podman.

Defaults: network: "none" (no egress), readOnlyRoot: true, capDrop: ["ALL"], image openclaw-sandbox:trixie-slim.

This explicit configuration keeps the agent workspace read-only and preserves the default restricted runtime posture:

json5
{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "docker",        scope: "session",        workspaceAccess: "ro",        docker: {          image: "openclaw-sandbox:trixie-slim",          readOnlyRoot: true,          tmpfs: ["/tmp", "/var/tmp", "/run"],          network: "none",          capDrop: ["ALL"],        },      },    },  },}

OpenClaw also creates Docker sandbox containers with an init process and no-new-privileges. With workspaceAccess: "ro", the agent workspace is mounted read-only at /agent; write operations to the agent workspace are rejected, while the configured tmpfs paths remain writable.

File tools require a host-backed bind mount. A tmpfs or image volume can hide files below a workspace bind; file tools report those paths as container-only instead of reading the hidden host files. Use exec to access that storage. A deeper explicit bind restores file-tool access when it is visible in the container. Mount destinations reached through symlinks, or stacked mounts with different backing storage, also require exec when their host projection cannot be established from the container's mount table.

For recently used containers, changes to bind sources or access modes, or to tmpfs destinations or read-only modes below a bind, require scoped recreation. Other tmpfs options, such as size, mode, and uid, keep the normal configuration change behavior: a hot container stays running with a recreation notice, while a stopped or expired container is replaced. Recreate explicitly to apply those options immediately.

After a Gateway restart, Docker and Podman tool containers can be replaced on their first use when an upgrade adds Gateway-managed read-only skill or resource mounts. Every existing mount must still match; replaced sources do not qualify. The old container must have a read-only root, no image volumes, and no retained persistent-exec custody; its last successful use must predate this Gateway process. Workspace and user bind sources and access modes must still match. Workspace files remain on the host, but replacement discards temporary container state and untracked background processes. Writable roots, user mount changes, restricted dispatch requiring current config, and hot browser containers still require explicit recreation.

To expose host GPUs, set agents.defaults.sandbox.docker.gpus (or the per-agent override) to a value like "all" or "device=GPU-uuid". This is passed to the selected container engine's Docker-compatible --gpus flag and requires compatible host GPU setup. Podman requires version 5.0 or newer for this option.

Sandboxed browser

  • The sandbox browser auto-starts and waits for CDP to become reachable when the browser tool needs it. Configure via agents.defaults.sandbox.browser.autoStart (default true) and autoStartTimeoutMs (default 12s).
  • Sandbox browser containers use a dedicated Docker network (openclaw-sandbox-browser) instead of the global bridge network. Configure with agents.defaults.sandbox.browser.network.
  • Sandbox browser network mode "none" is unsupported because browser control requires host-published CDP ports. Use the dedicated default, bridge, or another custom bridge network. openclaw doctor --fix disables affected persisted sidecars and restores the dedicated network without silently enabling egress.
  • agents.defaults.sandbox.browser.cdpSourceRange restricts container-edge CDP ingress with a CIDR allowlist (for example 172.21.0.1/32).
  • noVNC observer access is password-protected by default; OpenClaw emits a short-lived token URL that serves a local bootstrap page and opens noVNC with the password in the URL fragment (not query string or header logs).
  • agents.defaults.sandbox.browser.allowHostControl (default false) lets sandboxed sessions target the host browser explicitly.
  • Optional allowlists gate target: "custom": allowedControlUrls, allowedControlHosts, allowedControlPorts.
Was this useful?