Deploy OpenClaw with Docker: Quick Setup Guide

Determine if Docker fits your OpenClaw setup

Deciding whether to containerize your Gateway depends on your specific environment and how you prefer to manage your local setup. Using Docker with OpenClaw provides a clean way to isolate your processes without cluttering your host system.

1. Choose Yes if you need an isolated, throwaway Gateway environment or want to run OpenClaw on a host where you cannot install local dependencies.
2. Choose No if you are working on your local machine and prefer the fastest development loop possible; in this case, the standard installation flow is better.
3. Keep in mind the Sandboxing note: while the default sandbox backend uses Docker when enabled, sandboxing is disabled by default and does not require the entire Gateway to run inside a container. You can also explore SSH and OpenShell sandbox backends in the Sandboxing documentation.

Check your Prerequisites for Docker deployment

Before you start the containerization process, you need to ensure your hardware and software meet the minimum requirements to avoid build failures. A stable Docker environment is essential for a smooth OpenClaw experience.

1. Install Docker Desktop (or Docker Engine) along with Docker Compose v2.
2. Ensure your host has at least 2 GB of RAM for the image build process, as pnpm install might trigger an OOM-kill (exit 137) on 1 GB systems.
3. Verify you have enough disk space to store images and logs generated by the Gateway.
4. If you plan to run this on a VPS or any public host, make sure to review the Security hardening for network exposure guide, specifically the Docker DOCKER-USER firewall policy.

Setting up a new tool can sometimes feel like a chore, especially when you have to deal with conflicting dependencies or environment issues. Using a Containerized Gateway is the best way to avoid these headaches and get your automation environment running smoothly.

Setting up an OpenClaw Containerized Gateway allows you to run the entire system in a predictable, isolated environment. This approach ensures that your OpenClaw instance behaves exactly the same way on your local machine as it does in production.

Deploy OpenClaw with Containerized Gateway

The easiest way to get started is by using the automated setup script provided in the repository. This script handles the image building and initial configuration so you can get up and running in minutes.

1. Build the image from the repo root by running 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 through the automated prompts. The setup script 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 by visiting http://127.0.0.1:18789/ in your browser. You will need to paste the configured shared secret into Settings; the setup script writes a token to .env by default, but 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 if you want to add messaging capabilities. Use the CLI container to add your preferred platforms:

    # 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

Run the Manual Docker Flow

If you prefer to have full control over every step instead of using the automated script, you can execute the commands manually. This is useful for debugging or integrating into your own custom deployment pipelines.

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

Run docker compose from the repo root. If you enabled OPENCLAW_EXTRA_MOUNTS or OPENCLAW_HOME_VOLUME, the setup script writes docker-compose.extra.yml; include it with -f docker-compose.yml -f docker-compose.extra.yml.

Because openclaw-cli shares openclaw-gateway’s network namespace, it is a post-start tool. Before docker compose up -d openclaw-gateway, run onboarding and setup-time config writes through openclaw-gateway with --no-deps --entrypoint node.

Configure Environment Variables

The setup script is flexible and accepts several optional environment variables to customize the build and runtime behavior. These variables allow you to inject extra packages or change how data is persisted.

Variable	Purpose
OPENCLAW_IMAGE	Use a remote image instead of building locally
OPENCLAW_DOCKER_APT_PACKAGES	Install extra apt packages during build (space-separated)
OPENCLAW_EXTENSIONS	Pre-install extension deps at build time (space-separated names)
OPENCLAW_EXTRA_MOUNTS	Extra host bind mounts (comma-separated source:target[:opts])
OPENCLAW_HOME_VOLUME	Persist /home/node in a named Docker volume
OPENCLAW_SANDBOX	Opt in to sandbox bootstrap (1, true, yes, on)
OPENCLAW_DOCKER_SOCKET	Override Docker socket path

Monitor Health Checks

Monitoring the health of your container is essential for maintaining a reliable service. OpenClaw includes built-in endpoints that you can query to verify if the gateway is alive and ready to handle requests.

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.

For an authenticated deep health snapshot, use this command:

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

Understand LAN vs Loopback Binding

The network binding setting determines how the gateway listens for incoming connections. By default, the setup script configures this to allow access from your host machine’s browser and CLI.

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

Use bind mode values in gateway.bind (lan / loopback / custom / tailnet / auto), not host aliases like 0.0.0.0 or 127.0.0.1.

Manage Storage and Persistence

To ensure your settings and agent data are not lost when you update or restart your container, OpenClaw uses specific bind mounts. These mounts map directories on your host machine to the appropriate locations inside the container.

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. You should also keep an eye on disk growth hotspots like media/, session JSONL files, cron/runs/*.jsonl, and rolling file logs under /tmp/openclaw/.

Install Shell Helpers with ClawDock

If you find yourself typing long Docker commands frequently, you should install ClawDock. These shell helpers simplify daily management tasks like starting, stopping, and accessing the dashboard.

1. Install the helpers by running this in your terminal:

    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.

2. Use the new commands to manage your gateway:

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

Advanced Configuration Options

There are several advanced settings you can use to harden your installation or add specific features. These options cover everything from security sandboxing to optimizing your Docker build process.

Enable agent sandbox for Docker gateway

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

Custom socket path (e.g. rootless Docker):

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

The script mounts docker.sock only after sandbox prerequisites pass. If sandbox setup cannot complete, the script resets agents.defaults.sandbox.mode to off.

Automation / CI (non-interactive)

Disable Compose pseudo-TTY allocation with -T:

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

Shared-network security note

openclaw-cli uses network_mode: "service:openclaw-gateway" so CLI commands can reach the gateway over 127.0.0.1. Treat this as a shared trust boundary. The compose config drops NET_RAW/NET_ADMIN and enables no-new-privileges on openclaw-cli.

Permissions and EACCES

The image runs as node (uid 1000). If you see permission errors on /home/node/.openclaw, make sure your host bind mounts are owned by uid 1000:

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

Faster rebuilds

Order your Dockerfile so dependency layers are cached. This avoids re-running pnpm install unless lockfiles change:

    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"]

Power-user container options

The default image is security-first and runs as non-root node. For a more full-featured container:

1. Persist /home/node: export OPENCLAW_HOME_VOLUME="openclaw_home"
2. Bake system deps: export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"
3. Install Playwright browsers:

   docker compose run --rm openclaw-cli \
     node /app/node_modules/playwright-core/cli.js install chromium

4. Persist browser downloads: set PLAYWRIGHT_BROWSERS_PATH=/home/node/.cache/ms-playwright and use OPENCLAW_HOME_VOLUME or OPENCLAW_EXTRA_MOUNTS.

OpenAI Codex OAuth (headless Docker)

If you pick OpenAI Codex OAuth in the wizard, it opens a browser URL. In Docker or headless setups, copy the full redirect URL you land on and paste it back into the wizard to finish auth.

Base image metadata

The main Docker image uses node:24-bookworm and publishes OCI base-image annotations including org.opencontainers.image.base.name, org.opencontainers.image.source, and others. See OCI image annotations.

Deploy OpenClaw on a VPS

Running your gateway on a Virtual Private Server ensures that your automations stay online even when your local machine is off. There are specific guides available for popular providers and general VM runtimes.

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

AI Setup Assistant

Next Steps

• Configure WhatsApp Channel
• Learn about Docker VM Runtime
• Set up ClawDock Helpers

Secure Your Environment with OpenClaw Agent Sandbox

When you activate the OpenClaw agent sandbox with the Docker backend, the Gateway runs tool executions like shell commands or file operations inside isolated containers. This approach keeps your host system safe while allowing agents to perform tasks in a controlled environment.

1. The sandbox provides a hard wall around untrusted or multi-tenant agent sessions without needing to containerize the entire Gateway.
2. You can set the sandbox scope to be per-agent (which is the default), per-session, or shared across multiple agents.
3. Every scope receives its own dedicated workspace that is mounted at /workspace inside the container.
4. You can configure network isolation and resource limits, or even set up browser containers for agents that need web access.

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

Enable Agent Sandbox in Your Configuration

You can quickly turn on this feature by modifying your JSON configuration file and running a setup script. This process ensures your Docker images are ready to handle agent sessions securely.

1. Update your configuration to include the sandbox settings under the agents defaults section.
2. Run the provided shell script from your CLI to build the default sandbox image on your machine.

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

Build the default sandbox image:

scripts/sandbox-setup.sh

When you run into issues with OpenClaw, troubleshooting usually involves checking your Docker environment or CLI configurations. Most problems can be fixed by verifying your sandbox setup or refreshing your device permissions.

Fix OpenClaw Sandbox Image and Container Startup Issues

If you find that your image is missing or the sandbox container refuses to start, you likely need to initialize the environment manually. You can fix this by building the image or pointing the configuration to your specific custom image.

1. Build the sandbox image using the script located at scripts/sandbox-setup.sh.
2. Or, you can set the agents.defaults.sandbox.docker.image configuration key to your own custom image.
3. Keep in mind that Docker containers are created automatically for each session whenever they are needed.

Resolve Permission Errors in the OpenClaw Sandbox

Permission issues usually happen when the user inside the container does not match the owner of the files on your host machine. You can align these identities to ensure the sandbox has the right access to your files.

1. Set the docker.user configuration to a UID:GID that matches the ownership of your mounted workspace.
2. Alternatively, you can use the chown command on your workspace folder to change its ownership to match the container user.

Find Custom Tools within the OpenClaw Sandbox

OpenClaw executes commands using sh -lc (a login shell), which sources /etc/profile and might reset your PATH. If your custom tools are not being found, you need to ensure they are correctly added to the shell environment.

1. Set docker.env.PATH to prepend your custom tool paths so they are recognized by the shell.
2. Or, you can add a setup script under the /etc/profile.d/ directory within your Dockerfile.

Fix OOM-Killed Errors During Image Build

If you see an exit 137 error during the image build process, it means the process was killed because it ran out of memory. This usually happens when the virtual machine does not have enough resources to complete the build.

1. Ensure your VM has at least 2 GB of RAM available for the build process.
2. Use a larger machine class and try the build again.

Fix Unauthorized Access or Pairing Issues in Control UI

When the dashboard shows unauthorized errors or asks for pairing, you need to refresh your session and approve your browser device through the CLI. This ensures that only authorized devices can access your OpenClaw instance.

1. Fetch a fresh dashboard link and make sure not to open it automatically by running:

    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>

2. List the devices that are requesting access:

docker compose run --rm openclaw-cli devices list

3. Approve the specific device by using its requestId:

docker compose run --rm openclaw-cli devices approve <requestId>

You can find more details in the Dashboard and Devices documentation.

Fix Gateway Target and Docker CLI Pairing Errors

If the Gateway target shows an internal IP like ws://172.x.x.x or you encounter pairing errors from the Docker CLI, you should reset the network binding. This forces the system to use the correct local or network interface.

1. Reset the Gateway mode and bind settings by running this command:

    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

2. Verify your device list by explicitly pointing to the local URL:

docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789

Explore more OpenClaw resources

If you want to expand your knowledge, these OpenClaw resources cover everything from alternative deployment methods to post-install tweaks. You can find specific guides for different environments and maintenance tasks here.

1. Install Overview — This guide covers all the different installation methods you can use to get started.
2. Podman — If you are looking for a Podman alternative to Docker, this is the guide for you.
3. ClawDock — This is a great Docker Compose community setup that makes deployment much easier.
4. Updating — You should check this regularly to ensure you are keeping OpenClaw up to date.
5. Configuration — Head over here to handle your Gateway configuration after you finish the install.