> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker agent sandbox and troubleshooting

Enabling the Docker agent sandbox, and fixes for sandbox images, permissions, and Control UI pairing. Part of the [Docker](https://docs2.openclaw.ai/install/docker.md) 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:

* [Sandboxing](https://docs2.openclaw.ai/gateway/sandboxing.md) -- complete sandbox reference
* [OpenShell](https://docs2.openclaw.ai/gateway/openshell.md) -- OpenShell-managed local or remote sandbox backend
* [Multi-agent sandbox and tools](https://docs2.openclaw.ai/tools/multi-agent-sandbox-tools.md) -- per-agent overrides

### Quick enable

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
scripts/sandbox-setup.sh
```

For npm installs without a source checkout, see [Sandboxing § Images and setup](https://docs2.openclaw.ai/gateway/sandboxing.md#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`](https://github.com/openclaw/openclaw/blob/main/scripts/sandbox-setup.sh) (source checkout) or the inline `docker build` command from [Sandboxing § Images and setup](https://docs2.openclaw.ai/gateway/sandboxing.md#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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> docker compose run --rm openclaw-cli dashboard --no-open
> docker compose run --rm openclaw-cli devices list
> docker compose run --rm openclaw-cli devices approve <requestId>
> ```
>
> More detail: [Dashboard](https://docs2.openclaw.ai/web/dashboard.md), [Devices](https://docs2.openclaw.ai/cli/devices.md).

> **Gateway target shows ws\://172.x.x.x or pairing errors from Docker CLI**
>
> Reset gateway mode and bind:
>
> ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
> 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
> ```