OpenClaw "Sandbox mode requires Docker" error: causes and fixes

The message, and the one beside it

Sandbox mode requires Docker, but the Docker daemon is not available.
Start Docker, or set `agents.defaults.sandbox.mode=off` to disable
sandboxing. Docker said: <Docker's own error>

OpenClaw raises it at the start of a sandboxed run, when it checks that the sandbox image exists and Docker’s reply says it could not connect (the check in OpenClaw’s source). Whatever follows “Docker said” is Docker’s own reason: a failure to connect means nothing answered at Docker’s socket, and a permission error means the daemon is there but the user the gateway runs as may not use it. A fallback model does not retry the run, because a different model would meet the same missing Docker. The wording is the same on 2026.9.4 and the current 2026.9.6.

When the docker command is missing altogether, the same situation reads differently, and comes from a different check:

Sandbox mode requires Docker, but the "docker" command was not found
in PATH. Install Docker (and ensure "docker" is available), or set
`agents.defaults.sandbox.mode=off` to disable sandboxing.

Everything below applies to both.

Something turned the sandbox on

Out of the box nothing is sandboxed, so one of three settings asked for it (OpenClaw’s modes and backends):

• agents.defaults.sandbox.mode set to non-main or all, which covers every agent. OpenClaw’s Docker setup script sets non-main when run with OPENCLAW_SANDBOX=1.
• An agent’s own agents.entries.<id>.sandbox.mode, which overrides the global setting for that agent. The documented mail-reader agents for the IMAP and Gmail triggers set it to all.
• A named operator role whose sandbox policy is required. That role’s new sessions are sandboxed whatever the agent’s mode, and if the backend is unavailable they fail closed: “backend failure never falls back to host execution.”

Rather than reading the config by eye, ask OpenClaw which one applies. openclaw sandbox explain prints the effective mode for an agent or a session, with the config keys to change:

openclaw sandbox explain --agent <agent-id>
openclaw sandbox explain --session <session-key>

openclaw doctor warns about a sandbox without Docker too, but its check reads only the global setting, so a sandbox switched on for one agent does not show up there. And openclaw sandbox list is not a Docker test: it lists sandboxes OpenClaw has already created, so it prints “No sandbox runtimes found” on a machine with Docker running and nothing sandboxed yet.

Why the main chat works and the rest fail

non-main sandboxes every session except the agent’s main one, agent:<id>:main. Everything else runs under a session key of its own: group chats and channels, isolated cron runs (cron:<job-id>), webhook runs and sub-agents. So the usual picture is that your own chat with the agent keeps working while scheduled jobs, group chats and sub-agents fail with this message. OpenClaw’s own doctor puts it the same way: “Isolated sessions (automations, sub-agents) will fail without Docker.” With all, the main chat fails as well. Sessions outside the sandbox need no Docker at all, and their tools run as usual.

Keep the sandbox: make Docker reachable

Docker has to answer the user the gateway runs as, not only you. The check doctor itself runs is one command; run it as that user:

docker version --format '{{.Server.Version}}'

A version number means OpenClaw will reach Docker too. If it fails, the reason is one of two:

• Docker is installed but not running. Docker Desktop is not open, or the Docker service is stopped on Linux (sudo systemctl start docker). Start it and send the message again.
• Docker works in your shell but not for the gateway. A permission error after “Docker said” means the user the gateway runs as may not use Docker’s socket, as happens when the gateway runs as a different user from your shell. Adding that user to the docker group fixes it once the gateway starts afresh with the new group: a running process keeps the groups it started with. For a system service, restarting it is enough; a user service or a gateway started from a login inherits its groups from that user’s session, and a reboot is the sure way to renew them. Then run the check above as that user again. Docker’s own docs are plain about what the group grants: “root-level privileges”. That is what the Docker backend needs on any machine: the sandbox walls in the agent’s tools, while the gateway that starts the containers controls Docker.

Then expect one more stop. OpenClaw does not pull its sandbox image or substitute a plain one, so the first sandboxed run on a fresh machine ends with “Sandbox image not found: openclaw-sandbox:bookworm-slim”. From a source checkout, scripts/sandbox-setup.sh builds it. The npm package does not include that script, and the images page gives the build inline:

docker build -t openclaw-sandbox:bookworm-slim - <<'DOCKERFILE'
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && apt-get install -y --no-install-recommends \
  bash ca-certificates curl git jq python3 ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN useradd --create-home --shell /bin/bash sandbox
USER sandbox
WORKDIR /home/sandbox
CMD ["sleep", "infinity"]
DOCKERFILE

When the gateway itself runs in Docker

A gateway in a container reaches the host’s Docker through a socket mounted into it, and OpenClaw’s Dockerfile installs the docker command only when built with OPENCLAW_INSTALL_DOCKER_CLI=1. Without the command you get the “not found in PATH” version of the error; with the command and no socket, this one.

The documented set-up is the Docker setup script run with OPENCLAW_SANDBOX=1. It builds the image with the command, writes the socket mount into a separate file, docker-compose.sandbox.yml, and sets the mode to non-main. Compose reads that file only when you name it with -f, and the docs ask for the same file set on every command. Bring the stack up with a plain docker compose up -d and the gateway comes back with sandboxing on and no socket: this error, in every session but the main one. Name every file your set-up uses, the sandbox file included; with no override or extra file, that is:

docker compose -f docker-compose.yml -f docker-compose.sandbox.yml \
  up -d openclaw-gateway

Know what the socket is before you mount it. Anything running in the gateway container can use it, including the shell commands of every session you did not sandbox, which under non-main means your main chat. Control of Docker lets a container start with the host’s filesystem inside it, which is why Docker says only trusted users should have it. OpenClaw’s docs draw one line firmly: never mount the socket into the sandbox containers themselves.

One version difference matters here. On 2026.9.4 and earlier, a containerised gateway needed the host’s absolute paths in its config, with the same paths mounted into the gateway. From 2026.9.5 (the pull request that changed it) you keep the gateway’s own paths, OpenClaw translates the workspace and skill mounts into the host’s, and the sources have to be bind mounts rather than named volumes, per the Docker backend page.

Keep a sandbox without Docker

Other backends run the same sandboxed tools somewhere else. Set agents.defaults.sandbox.backend, or the agent’s own, to one of these:

• podman: a local Podman engine, used directly, with no fallback to Docker. It needs catatonit on the engine host and the sandbox image built into Podman’s store, and it has no sandboxed browser.
• ssh: tools run on another machine over SSH, which needs /bin/sh, python3 and GNU stat and readlink. The workspace is copied there once and the remote copy becomes the real one, with no sync back; there is no sandboxed browser, and the network is whatever that machine allows (SSH backend).
• crabbox: a throwaway cloud machine leased through Crabbox, documented since 2026.9.5, with initial support for Daytona leases. OpenClaw’s docs describe it as “the option for a personal Gateway that should keep its setup local but must not run model-generated commands on the host and cannot or should not run Docker.”
• openshell: a plugin backend for NVIDIA’s OpenShell sandboxes. It needs a reachable OpenShell gateway, and a local one needs a supported compute runtime on its own host.

The sandboxed browser needs the Docker backend itself; on any other backend, keep sandbox.browser.enabled off.

Or turn it off where it was turned on

If nothing needs the sandbox, switch it off at the level that switched it on. The global setting is the command OpenClaw’s error and doctor both suggest:

openclaw config set agents.defaults.sandbox.mode off

An agent’s own setting wins over that one, so a sandbox set on a single agent is switched off there:

openclaw config set agents.entries.<agent-id>.sandbox.mode off

A role that requires a sandbox has no per-session way out; its policy is the setting to change. Know what goes with it: without a sandbox, the agent’s tools run on the gateway’s machine as the gateway’s user, and the walls left are tool policy and exec approvals. The guide to OpenClaw’s sandbox and approvals covers which of them stops what.

The email-reader recipes

OpenClaw’s documented mail readers lead straight here. The IMAP trigger’s recipe gives its reader agent a sandbox of its own (mode: "all", scope: "session", workspaceAccess: "none"), says “The reader requires an available sandbox backend,” and its first test stops at one of these messages when Docker is out of reach:

openclaw agent --agent mail_reader --message "Reply exactly MAIL_READER_OK"

The Gmail Pub/Sub recipe lists “a working sandbox backend” among its prerequisites.

The same recipe allows the reader one tool, session_status, and denies the file, shell, web and browser tools among others. The sandbox is part of that design: the recipe requires a working backend, and for a more capable mail agent the Gmail docs’ advice is to “sandbox the run”. For these readers, the fix is a backend that answers, from the sections above.

The reader also only reads: it does not reply or save attachments. For an agent that does those, the route is a scheduled check of the mailbox by an agent with the tools for it, which the email assistant guide sets up. Sandboxing is off by default, so that route needs no sandbox backend.