OpenClaw Docker: Containerize Your Agent and Deploy Anywhere

Three teams we work with tried running OpenClaw directly on bare metal first. Every one of them switched to Docker within two weeks. The gap between "works on my machine" and "works in production" closes completely when you containerize — and with OpenClaw, the Dockerfile is simpler than most people expect.

Why Docker Changes Everything for OpenClaw

OpenClaw agents depend on a specific combination of Python version, system libraries, and configuration files. On a bare metal server, those dependencies drift over time. A system update pulls in a new library version. A developer installs something for an unrelated project. Months later, your agent crashes on a dependency conflict nobody can trace.

Docker eliminates that problem entirely. The container is the environment. It's frozen at build time, portable across any host running Docker, and completely isolated from the host OS. You build once and run anywhere without surprises.

Beyond dependency management, Docker gives you instant rollback. Something breaks in production? docker run the previous image tag. No manual dependency restoration, no system state to unwind.

The Production Dockerfile

Here's the Dockerfile we use for every OpenClaw agent deployment. Each line is deliberate — no bloat, no unnecessary layers.

# OpenClaw Agent — Production Dockerfile
FROM python:3.11-slim

# Set working directory
WORKDIR /app

# Install system dependencies first (cached layer)
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Copy requirements before source code (Docker layer cache optimization)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application source
COPY . .

# Create data directory for volumes
RUN mkdir -p /app/data

# Create non-root user for security
RUN useradd -r -s /bin/false openclaw && \
    chown -R openclaw:openclaw /app
USER openclaw

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=15s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1

# Expose gateway port
EXPOSE 8080

CMD ["python", "-m", "openclaw", "start"]

The layer ordering is intentional. Dependencies go before source code so Docker's build cache reuses the pip install layer whenever you change source files but not requirements. That keeps rebuild times under 10 seconds on a warm build.

The non-root user matters in production. Running as root inside a container isn't an automatic disaster, but it violates least-privilege principles and fails security scans in regulated environments. The openclaw user owns the app directory and nothing else.

Build and Run Commands

Building the image takes about 90 seconds on first build, under 15 seconds on subsequent builds with warm cache.

# Build with a version tag
docker build -t openclaw-agent:1.0.0 .
docker tag openclaw-agent:1.0.0 openclaw-agent:latest

# Run with environment variables
docker run -d \
  --name openclaw-gateway \
  --restart unless-stopped \
  -p 8080:8080 \
  -e OPENAI_API_KEY=sk-... \
  -e GATEWAY_TOKEN=your-secret-token \
  -v openclaw-data:/app/data \
  openclaw-agent:latest

The --restart unless-stopped flag tells Docker to bring the container back up automatically after a host reboot or unexpected crash. This is the difference between an agent that runs 24/7 and one that disappears silently after the next system update.

Sound familiar? Every team forgets the restart policy on their first VPS deployment. They notice the agent is gone three days later when someone tries to use it.

Volumes and Persistence

Without a volume mount, all OpenClaw data — conversation history, shared memory, downloaded model configs — lives inside the container's writable layer. Stop the container, that data is gone. Start a new container from the same image and you're starting from scratch.

That's fine for development. It's a disaster for production.

# Create a named volume (Docker manages the storage location)
docker volume create openclaw-data

# Mount it at /app/data
docker run -d \
  --name openclaw-agent \
  -v openclaw-data:/app/data \
  openclaw-agent:latest

# Inspect volume contents
docker run --rm -v openclaw-data:/data alpine ls /data

Named volumes persist independently of containers. You can stop, remove, and replace the container without losing any data. When you upgrade to a new image version, mount the same volume and the agent picks up exactly where it left off.

Environment Variables and Secrets

OpenClaw reads its configuration from environment variables at startup. The critical ones are your LLM API keys and the gateway token. Here's how to pass them safely without baking them into your image.

# Create a .env file (add to .gitignore immediately)
OPENAI_API_KEY=sk-proj-...
ANTHROPIC_API_KEY=sk-ant-...
GATEWAY_TOKEN=your-32-char-random-secret
OPENCLAW_LOG_LEVEL=info
OPENCLAW_DATA_DIR=/app/data

# Run with the env file
docker run -d \
  --name openclaw-agent \
  --env-file .env \
  -v openclaw-data:/app/data \
  -p 8080:8080 \
  openclaw-agent:latest

The --env-file flag reads key-value pairs from a file. Keep that file out of version control. If you use a CI/CD pipeline, inject the secrets from your pipeline's secret store — GitHub Actions secrets, GitLab CI variables, or AWS Secrets Manager — rather than committing a plaintext env file anywhere.

As of early 2025, Docker BuildKit supports build secrets that never appear in layer history. For environments with strict compliance requirements, use --secret during build instead of ARG for any secret values needed at build time.

Common Docker Mistakes With OpenClaw

• Using the full Python image — python:3.11 is 900MB. python:3.11-slim is under 200MB and includes everything OpenClaw needs. The bloat in the full image is build tools you don't use at runtime.
• Copying source code before requirements — if requirements go after source, every source code change invalidates the pip install cache layer. Reverse the order and rebuilds take seconds instead of minutes.
• Running as root — it works, but security scanners flag it and some cloud environments block it by policy. Add the non-root user from the start.
• Forgetting the restart policy — containers stopped by a host reboot or crash don't restart automatically without --restart unless-stopped. This is the single most common reason agents silently disappear.
• Not adding a health check — without a health check, Docker has no way to detect a hung process that's still technically running. Add the HEALTHCHECK directive and orchestrators can restart unhealthy containers automatically.

Frequently Asked Questions

What base image should I use for OpenClaw Docker?

Use python:3.11-slim as your base image. It includes everything OpenClaw needs while keeping the image under 200MB. The full python:3.11 image works but adds 400MB of unnecessary build tools you don't need at runtime.

How do I pass my API keys into an OpenClaw Docker container?

Pass secrets as environment variables using the -e flag or an env file: docker run --env-file .env openclaw-agent. Never bake API keys into the image — they end up in layer history and any registry you push to. Use Docker secrets for Swarm or Kubernetes secret objects for K8s.

How do I persist OpenClaw data across container restarts?

Mount a named volume to the /app/data directory: -v openclaw-data:/app/data. This preserves conversation history, memory state, and any downloaded models across container restarts. Without a volume mount, all agent state is lost when the container stops.

Can I run multiple OpenClaw agents in one Docker container?

You can, but you shouldn't. One agent per container is the correct pattern. It gives you independent scaling, isolated failure domains, and clean restart behavior. Use Docker Compose or Kubernetes to orchestrate multiple agents as separate containers.

How do I check OpenClaw logs in Docker?

Run docker logs -f container-name to follow live logs. For structured log output, set LOG_FORMAT=json in your environment variables so logs parse correctly in tools like Datadog, Loki, or CloudWatch. Without -f the command shows historical logs and exits.

What ports does OpenClaw expose in Docker?

The gateway exposes port 8080 by default. Map it to any host port with -p 8080:8080 or a custom port like -p 443:8080. Individual agents don't expose ports — they connect outbound to the gateway. Only the gateway needs a published port for external access.