Docker-out-of-Docker path constraints documented
Deploying the OpenClaw Gateway in Docker? New documentation explains the critical path mapping requirements that prevent confusing EACCES permission errors when heartbeats try to write across container boundaries.
When the OpenClaw Gateway runs inside a Docker container, it orchestrates sibling sandbox containers on the host using the Docker socket. This Docker-out-of-Docker (DooD) setup introduces a subtle path mapping constraint that has been undocumented — until now.
A new section in the sandboxing documentation explains that the workspace path must reference the host's absolute filesystem path, not the internal container path. This is because the Docker daemon evaluates paths against the host namespace, while the Gateway's native process evaluates the same string from within its containerized environment.
The documentation now makes clear that deployments must include identical volume mappings across both namespaces. Without this parity, OpenClaw throws an EACCES permission error when attempting to write heartbeat or bridge files, since the fully qualified path doesn't exist in the container's native filesystem.
This guidance applies to the file, adding a dedicated "Docker backend" section that documents constraints specific to DooD deployments.
View Original GitHub Description
Add warning and constraints for Docker-out-of-Docker sandbox deployments
OpenClaw's architecture requires host absolute path parity when deploying the Gateway in a Docker container alongside sandbox socket bridging. Because the internal Gateway node process evaluates the same configuration path variable as the upstream Docker socket, orchestrators MUST inject their Host path absolutely into openclaw.json and must supply an identical volume map across that namespace.
Found while investigating EACCES permission errors in the OpenClaw sandbox when heartbeat attempts hit mapped directories.
Refs OpenClaw Host-State Bleed Debugging