Docker (optional)

Docker is optional. Use it only if you want a containerized gateway or to validate the Docker flow.

Is Docker right for me?

• Yes: you want an isolated, throwaway gateway environment or to run OpenClaw on a host without local installs.
• No: you are running on your own machine and just want the fastest dev loop. Use the normal install flow instead.
• Sandboxing note: agent sandboxing uses Docker too, but it does not require the full gateway to run in Docker. See Sandboxing.

Prerequisites

• Docker Desktop (or Docker Engine) + Docker Compose v2
• At least 2 GB RAM for image build (pnpm install may be OOM-killed on 1 GB hosts with exit 137)
• Enough disk for images and logs
• If running on a VPS/public host, review Security hardening for network exposure, especially Docker DOCKER-USER firewall policy.

Containerized Gateway

1. Build the image

   From the repo root, run the setup script:

   ./scripts/docker/setup.sh
   

   This builds the gateway image locally. To use a pre-built image instead:

   export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
   ./scripts/docker/setup.sh
   

   Pre-built images are published at the GitHub Container Registry. Common tags: main, latest, <version> (e.g. 2026.2.26).

2. Complete onboarding

   The setup script runs onboarding automatically. It will:

   • prompt for provider API keys
   • generate a gateway token and write it to .env
   • start the gateway via Docker Compose

   During setup, pre-start onboarding and config writes run through openclaw-gateway directly. openclaw-cli is for commands you run after the gateway container already exists.

3. Open the Control UI

   Open http://127.0.0.1:18789/ in your browser and paste the configured shared secret into Settings. The setup script writes a token to .env by default; if you switch the container config to password auth, use that password instead.

   Need the URL again?

   docker compose run --rm openclaw-cli dashboard --no-open
   

4. Configure channels (optional)

   Use the CLI container to add messaging channels:

   # WhatsApp (QR)
   docker compose run --rm openclaw-cli channels login
   
   # Telegram
   docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"
   
   # Discord
   docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
   

   Docs: WhatsApp, Telegram, Discord

Manual flow

If you prefer to run each step yourself instead of using the setup script:

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon
docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'
docker compose up -d openclaw-gateway

Environment variables

The setup script accepts these optional environment variables:

Health checks

Container probe endpoints (no auth required):

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

The Docker image includes a built-in HEALTHCHECK that pings /healthz. If checks keep failing, Docker marks the container as unhealthy and orchestration systems can restart or replace it.

Authenticated deep health snapshot:

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

LAN vs loopback

scripts/docker/setup.sh defaults OPENCLAW_GATEWAY_BIND=lan so host access to http://127.0.0.1:18789 works with Docker port publishing.

• lan (default): host browser and host CLI can reach the published gateway port.
• loopback: only processes inside the container network namespace can reach the gateway directly.

Storage and persistence

Docker Compose bind-mounts OPENCLAW_CONFIG_DIR to /home/node/.openclaw and OPENCLAW_WORKSPACE_DIR to /home/node/.openclaw/workspace, so those paths survive container replacement.

That mounted config directory is where OpenClaw keeps:

• openclaw.json for behavior config
• agents/<agentId>/agent/auth-profiles.json for stored provider OAuth/API-key auth
• .env for env-backed runtime secrets such as OPENCLAW_GATEWAY_TOKEN

For full persistence details on VM deployments, see Docker VM Runtime - What persists where.

Disk growth hotspots: watch media/, session JSONL files, cron/runs/*.jsonl, and rolling file logs under /tmp/openclaw/.

Shell helpers (optional)

For easier day-to-day Docker management, install ClawDock:

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

If you installed ClawDock from the older scripts/shell-helpers/clawdock-helpers.sh raw path, rerun the install command above so your local helper file tracks the new location.

Then use clawdock-start, clawdock-stop, clawdock-dashboard, etc. Run clawdock-help for all commands. See ClawDock for the full helper guide.

export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh

docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]

Running on a VPS?

See Hetzner (Docker VPS) and Docker VM Runtime for shared VM deployment steps including binary baking, persistence, and updates.

Agent Sandbox

When agents.defaults.sandbox is enabled, the gateway runs agent tool execution (shell, file read/write, etc.) inside isolated Docker containers while the gateway itself stays on the host. This gives you a hard wall around untrusted or multi-tenant agent sessions without containerizing the entire 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, see:

• Sandboxing -- complete sandbox reference
• OpenShell -- interactive shell access to sandbox containers
• Multi-Agent Sandbox and Tools -- per-agent overrides

Quick enable

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

Build the default sandbox image:

scripts/sandbox-setup.sh

Troubleshooting

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>

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

Related

• Install Overview — all installation methods
• Podman — Podman alternative to Docker
• ClawDock — Docker Compose community setup
• Updating — keeping OpenClaw up to date
• Configuration — gateway configuration after install