OpenClaw's Sandbox Docs Finally Name the Docker-out-of-Docker Trap Behind Those Mystery EACCES Crashes

Here's the failure mode that inspired the warning. You deploy the OpenClaw Gateway as a Docker container, mount the host Docker socket so the Gateway can orchestrate sandbox containers for its agents, and wire up a workspace volume the way every runbook for containerized services tells you to. Everything boots. The first sandbox launches. Then the heartbeat hits disk and the whole thing falls over with a permission error on a path that, as far as you can see from inside the Gateway container, definitely exists and is definitely writable.

That's not a Gateway bug. It's not a filesystem bug. It's a deeply specific consequence of running one Docker daemon on behalf of another container — a pattern the Docker community calls Docker-out-of-Docker, or DooD, to distinguish it from the nested daemon variant. And it comes with exactly one rule that nobody enforces for you: the host and the guest have to agree, letter for letter, about where the workspace lives.

OpenClaw's automation reference now says so, on the page where people who are debugging at two in the morning will actually find it.

What the New Section Actually Says

The update adds a “Docker backend” subsection to OpenClaw's gateway sandboxing reference, right above the existing SSH backend notes. It lays out two hard constraints for anyone running the Gateway itself inside Docker while bridging to the host Docker socket for sandbox containers. Neither is subtle. Both have been silently assumed for months.

Why the Warning Took So Long

DooD has been a standard pattern for containerized CI runners for the better part of a decade. Anyone who has wired Jenkins, GitLab Runner, or BuildKit into a Docker socket has tripped on the same rule: paths leak. The daemon doesn't know or care that the client asking it to mount a volume is itself running in a container. It resolves every path string against the host filesystem and trusts the caller to have done the translation.

OpenClaw's Gateway has been quietly inheriting that contract since the Docker sandbox backend shipped. The reference code worked, because the reference setup happened to bind the host workspace under the same literal path inside the container. But the moment someone followed a more typical Dockerfile pattern — mount the host workspace at /app/workspaces, keep the config field pointing at the in-container path — the heartbeat started failing. The error message said EACCES. The real cause said nothing at all.

The update doesn't change any runtime behavior. The Gateway still speaks to the Docker socket the way it always has. What it changes is the contract between the operator writing openclaw.json and the project shipping the binary: the assumption is now on the page, in the section operators are already reading when sandboxing doesn't work.

“The Gateway deployment MUST include an identical volume map linking the host namespace natively.” — the new line now sitting at the top of the Docker backend section, where a year's worth of confused deployment tickets should have lived.

What to Check in Your Own Install

If you're running the Gateway in Docker today and you've been chasing intermittent sandbox failures or heartbeat errors in the logs, the two things to inspect are straightforward. First, open openclaw.json and verify that the workspace field is the absolute path as it exists on the host machine — the same string you'd see running ls on the host, not inside the container. Second, check your Compose file or docker run flags for the volume entry, and confirm that the host side and the container side are the same literal path. If they're not, fix one of them and restart the Gateway. The heartbeat will follow.

Docker-out-of-Docker has been silently tripping up container platforms for a decade. OpenClaw's sandboxing reference just became one of the few that explains exactly which wire you're about to walk into.