OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Containers

Docker agent sandbox and troubleshooting

Enabling the Docker agent sandbox, and fixes for sandbox images, permissions, and Control UI pairing. Part of the Docker guide.

Agent sandbox

When agents.defaults.sandbox is enabled with the Docker backend, the gateway runs agent tool execution (shell, file read/write, etc.) inside isolated Docker containers while the gateway itself stays on the host — a hard wall around untrusted or multi-tenant agent sessions without containerizing the whole gateway.

Sandbox scope can be per-agent (default), per-session, or shared; each scope gets its own workspace mounted at /workspace. You can also configure allow/deny tool policies, network isolation, resource limits, and browser containers.

For full configuration, images, security notes, and multi-agent profiles:

Quick enable

json5
{  agents: {    defaults: {      sandbox: {        mode: "non-main", // off | non-main | all        scope: "agent", // session | agent | shared      },    },  },}

Build the default sandbox image (from a source checkout):

bash
scripts/sandbox-setup.sh

For npm installs without a source checkout, see Sandboxing § Images and setup for inline docker build commands.

Troubleshooting

Image missing or sandbox container not starting

Build the sandbox image with scripts/sandbox-setup.sh (source checkout) or the inline docker build command from Sandboxing § Images and setup (npm install), or set agents.defaults.sandbox.docker.image to your custom image. Containers are auto-created per session on demand.

Permission errors in sandbox

Set docker.user to a UID:GID that matches your mounted workspace ownership, or chown the workspace folder.

Custom tools not found in sandbox

OpenClaw runs commands with sh -lc (login shell), which sources /etc/profile and may reset PATH. Set docker.env.PATH to prepend your custom tool paths, or add a script under /etc/profile.d/ in your Dockerfile.

OOM-killed during image build (exit 137)

A local source image build needs at least 6 GB RAM. Use a larger machine class or a pre-built image and retry.

Unauthorized or pairing required in Control UI

Fetch a fresh dashboard link and approve the browser device:

bash
docker compose run --rm openclaw-cli dashboard --no-opendocker compose run --rm openclaw-cli devices listdocker compose run --rm openclaw-cli devices approve <requestId>

More detail: Dashboard, Devices.

Gateway target shows ws://172.x.x.x or pairing errors from Docker CLI

Reset gateway mode and bind:

bash
docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789
Was this useful?
On this page

On this page