Install OpenClaw with Docker

Docker provides the most straightforward and reliable method for deploying OpenClaw across any operating system. By containerizing OpenClaw, you eliminate dependency conflicts, ensure consistent behavior across environments, and simplify updates and maintenance. This guide will walk you through every aspect of Docker-based OpenClaw deployment, from initial setup to production-ready configurations.

OpenClaw's Docker image is officially maintained and includes all necessary dependencies pre-configured. The image is based on Node.js 22 Alpine for minimal footprint while maintaining full functionality. Whether you're setting up a personal assistant on your local machine or deploying to a cloud server, Docker ensures a consistent, reproducible installation process.

Why Choose Docker for OpenClaw?

Docker deployment offers several compelling advantages for OpenClaw users. First, isolation ensures that OpenClaw runs in its own contained environment, preventing conflicts with other applications on your system. Second, portability means your configuration travels with the container, making it easy to move between machines or scale horizontally. Third, security benefits from Docker's sandboxing capabilities, which align perfectly with OpenClaw's recommended security practices.

The official OpenClaw Docker image includes the Gateway daemon, WebChat UI, and all core skills pre-installed. You can extend functionality by mounting additional skill directories or connecting to external services through Docker's networking capabilities. The image supports both x86_64 and ARM64 architectures, making it suitable for deployment on everything from cloud servers to Raspberry Pi devices.

Architecture Overview

When running OpenClaw in Docker, the container hosts the Gateway process that manages all channel connections and agent sessions. The Gateway exposes a WebSocket control plane on port 18789 by default, which clients use for communication. The WebChat UI is served on the same port, providing browser-based access to your assistant. For media handling and canvas features, an additional port (18793) serves static files.

Understanding this architecture helps you configure networking, storage, and security appropriately. The Gateway maintains persistent connections to messaging platforms, so container restarts require re-authentication with some channels (particularly WhatsApp). Proper volume mounting ensures your session data, configurations, and conversation history persist across container lifecycles.

For those eager to get started quickly, here's the fastest path to a running OpenClaw instance. This minimal setup gets you operational in under five minutes, though we recommend reading the full guide for production deployments.

One-Command Installation

The simplest way to start OpenClaw with Docker uses a single command that pulls the latest image and starts the container with sensible defaults. Open your terminal and execute the following command to launch OpenClaw immediately.

This command creates a new container named 'openclaw' with the configuration directory mounted for persistence. The Gateway will start automatically and begin the onboarding process. Access the WebChat interface at http://localhost:18789 to complete setup through the browser-based wizard.

Verifying the Installation

After starting the container, verify that OpenClaw is running correctly by checking the container logs. The logs should show the Gateway starting up, loading configurations, and listening for connections. Look for the message indicating the WebSocket server is ready on port 18789.

You can also verify the installation by accessing the health endpoint. A successful response indicates that the Gateway is operational and ready to accept connections. If you encounter issues at this stage, the troubleshooting section later in this guide addresses common problems.

Initial Configuration

With the container running, navigate to http://localhost:18789 in your browser to access the OpenClaw dashboard. The first-time setup wizard guides you through essential configuration steps including API key setup, channel connections, and basic preferences. Complete each step carefully, as these settings form the foundation of your OpenClaw installation.

This section provides comprehensive installation instructions with explanations for each step. Following these detailed instructions ensures a properly configured, secure, and maintainable OpenClaw deployment.

Step 1: Verify Docker Installation

Before proceeding, confirm that Docker is properly installed and running on your system. Execute the version check command to see your installed Docker version. OpenClaw requires Docker Engine 24.0 or later for full compatibility with all features. If you're running an older version, update Docker before continuing.

Also verify that your user account has permission to run Docker commands without sudo. On Linux systems, this typically requires adding your user to the docker group. Running Docker as root is not recommended for security reasons, and OpenClaw's documentation assumes non-root Docker access.

Step 2: Create Directory Structure

OpenClaw stores configuration, session data, and workspace files in specific directories. Creating these directories before starting the container ensures proper permissions and organization. The main directories needed are the configuration directory for openclaw.json and channel credentials, the workspace directory for agent files and skills, and the data directory for session storage and logs.

Setting appropriate permissions on these directories is crucial for security. The container runs as a non-root user (UID 1000 by default), so directories must be writable by this user. On Linux systems, adjust ownership with chown commands. On Windows and macOS with Docker Desktop, permission handling is typically automatic.

Step 3: Pull the Official Image

Pull the official OpenClaw Docker image from Docker Hub. The 'latest' tag always points to the most recent stable release. For production deployments, consider pinning to a specific version tag to ensure reproducible builds and controlled updates.

The initial pull downloads approximately 500MB of data, comprising the Node.js runtime, OpenClaw application, and all dependencies. Subsequent pulls for updates are much faster due to Docker's layer caching. Verify the pull completed successfully by listing your local images.

Step 4: Create Configuration File

Before starting the container, create a minimal configuration file. This file specifies your AI model preferences, channel configurations, and other settings. The configuration uses JSON format and lives in the config directory you created earlier.

At minimum, configure your preferred AI model provider. OpenClaw supports Anthropic, OpenAI, OpenRouter, and local models. The example configuration shows Anthropic's Claude model, which is recommended for optimal performance. Add your API key either directly in the config file (not recommended for shared systems) or through environment variables.

Step 5: Start the Container

With preparation complete, start the OpenClaw container using the comprehensive Docker run command. This command includes all recommended options for a production-quality deployment including volume mounts, environment variables, port mappings, and restart policies.

The command uses several important flags: --restart unless-stopped ensures the container restarts automatically after system reboots, -v flags mount your local directories into the container for persistence, -e flags pass environment variables for sensitive configuration, and -p flags expose necessary ports for web access and API communication.

Step 6: Complete Onboarding

With the container running, complete the onboarding process through the web interface. Navigate to http://localhost:18789 in your browser. The onboarding wizard walks you through connecting your first messaging channel, configuring agent behavior, and testing the installation with a sample conversation.

During onboarding, you'll authenticate with your chosen messaging platforms. WhatsApp requires scanning a QR code, Telegram needs a bot token, and Discord requires OAuth authorization. Each platform's connection process is documented in our integration guides, linked in the related guides section below.

For more complex deployments or easier management, Docker Compose provides a declarative way to define your OpenClaw setup. Compose files capture all container configuration in a single, version-controlled file, making deployments reproducible and documentation automatic.

Basic Compose File

Create a docker-compose.yml file in your OpenClaw project directory. This file defines the OpenClaw service with all necessary configurations. The compose format is more readable than long docker run commands and supports additional features like health checks and resource limits.

The compose file shown in our code examples includes volume definitions, environment variable configuration, port mappings, and a health check. The health check ensures that orchestration tools and monitoring systems can accurately report container status.

Adding Persistent Storage

The compose file uses named volumes for better lifecycle management. Named volumes persist independently of containers, survive compose down operations, and can be easily backed up. Define volumes for configuration, workspace, and data directories to ensure nothing is lost during updates or restarts.

For backup purposes, named volumes can be accessed directly through Docker commands or by mounting them to temporary containers. Document your volume names and backup procedures as part of your operational runbook.

Environment Variables

Compose supports multiple methods for environment variable management. For development, variables can be listed directly in the compose file. For production, use an env_file directive pointing to a .env file that's excluded from version control. This approach keeps secrets out of your repository while maintaining configuration flexibility.

Essential environment variables include ANTHROPIC_API_KEY or OPENAI_API_KEY for AI model access, OPENCLAW_CONFIG_DIR for configuration location override, and TZ for timezone settings affecting scheduled tasks and log timestamps.

Starting with Compose

Launch your OpenClaw deployment with docker compose up -d. The -d flag runs containers in detached mode. View logs with docker compose logs -f openclaw. Stop the deployment with docker compose down, which preserves volumes by default. Add -v flag to also remove volumes during teardown.

Proper network configuration ensures secure, reliable communication between OpenClaw and your devices. This section covers port configuration, reverse proxy setup, and remote access options.

Port Requirements

OpenClaw requires two ports for full functionality. Port 18789 hosts the WebSocket control plane and WebChat interface. Port 18793 serves the Canvas feature's static files. For basic operation with just messaging channels, only port 18789 is strictly required.

By default, the Docker examples bind ports to all interfaces (0.0.0.0). For local-only access, bind to 127.0.0.1 instead. This prevents external access while allowing local browser connections. The security section discusses network isolation in more detail.

Reverse Proxy Setup

For production deployments with HTTPS, place OpenClaw behind a reverse proxy like Nginx, Caddy, or Traefik. The proxy handles TLS termination, provides a friendly domain name, and adds an additional security layer. OpenClaw's Gateway communicates with the proxy over HTTP internally.

When configuring your reverse proxy, ensure WebSocket upgrade headers are properly forwarded. OpenClaw relies heavily on WebSocket connections, and missing headers cause connection failures. Our code examples show proper Nginx configuration for WebSocket proxying.

Remote Access Options

For accessing OpenClaw from outside your local network, several options exist. Tailscale provides the simplest secure remote access through its VPN mesh. OpenClaw includes built-in Tailscale support with serve and funnel modes. Alternatively, traditional VPN solutions, SSH tunnels, or reverse proxy with authentication all work well.

Avoid exposing OpenClaw directly to the public internet without authentication. The WebChat interface and API endpoints should be protected by authentication when accessible externally. Tailscale Funnel mode includes password protection for this reason.

Ensuring data persistence protects your configurations, conversation history, and channel sessions. This section explains what data needs persistence and how to implement reliable backup strategies.

Critical Data Directories

Three directories contain data that must persist across container restarts. The configuration directory (~/.openclaw) holds openclaw.json, channel credentials, and skill configurations. The workspace directory (~/.openclaw/workspace) contains agent files, AGENTS.md, SOUL.md, and installed skills. The data directory stores session information and SQLite databases for conversation history.

Loss of configuration data requires reconfiguring OpenClaw from scratch. Loss of channel credentials requires re-authenticating with each messaging platform. Loss of workspace data means recreating any custom agents or skills. Loss of session data results in conversation history being unavailable.

Volume Mount Strategies

Docker supports two main volume approaches: bind mounts and named volumes. Bind mounts link a specific host directory to a container path, giving direct filesystem access for editing and backup. Named volumes are managed by Docker, offering better isolation and performance but requiring Docker commands for access.

For development and small deployments, bind mounts simplify configuration editing and backup. For production deployments, named volumes with regular backup scripts provide better isolation and performance. Our compose examples demonstrate both approaches.

Backup Procedures

Implement regular backups of your OpenClaw data. For bind mounts, standard filesystem backup tools work directly. For named volumes, create backup scripts that mount volumes to temporary containers and copy data to backup locations.

Test your backup restoration process before you need it. A backup you haven't tested isn't a backup. Document the restoration procedure and verify it works with your current container configuration. Include API key re-entry in your restoration checklist, as these shouldn't be backed up for security reasons.

Docker provides isolation, but additional security measures ensure your OpenClaw deployment remains protected. This section covers container security, network isolation, and secrets management.

Running as Non-Root

The official OpenClaw image runs as a non-root user (UID 1000) by default. Never modify this to run as root. Non-root execution limits the blast radius of any potential security vulnerabilities. Ensure your volume mounts are writable by UID 1000 or configure the user directive in your compose file to match your host system.

Network Isolation

Create a dedicated Docker network for OpenClaw rather than using the default bridge network. Dedicated networks provide better isolation and allow fine-grained control over which containers can communicate. If running additional services like databases or proxies, place them on the same network for internal communication while restricting external access.

Bind ports to 127.0.0.1 rather than 0.0.0.0 when external access isn't required. This prevents any network-level access to OpenClaw from other machines on your local network. Use a reverse proxy for controlled external access with proper authentication.

Secrets Management

Never store API keys directly in configuration files that might be version controlled or backed up to insecure locations. Use Docker secrets in Swarm mode, environment variables passed at runtime, or external secrets managers like HashiCorp Vault.

The environment variable approach works well for most deployments: keep a .env file with your secrets, reference it in docker-compose.yml, and ensure .env is in your .gitignore. For production, consider secrets management services that provide audit logging and rotation capabilities.

Image Verification

Always pull images from the official openclaw repository on Docker Hub. Verify image integrity by checking the digest against published values. Enable Docker Content Trust to enforce signature verification on pulls. Be cautious of community images that might contain modifications.

Regular updates ensure you have the latest features, security patches, and bug fixes. Docker makes updating straightforward while maintaining your data through proper volume configuration.

Update Process

The update process involves pulling the new image, stopping the current container, and starting a new container with the updated image. Your data persists in volumes, so no migration is typically required. Before updating, review the release notes for any breaking changes or new configuration requirements.

For docker run deployments, stop and remove the existing container, pull the new image, then run the start command again. For Compose deployments, docker compose pull fetches updated images, then docker compose up -d recreates containers with new images while preserving volumes.

Version Pinning

Production deployments should pin to specific version tags rather than using 'latest'. This ensures reproducible deployments and prevents unexpected changes from automatic updates. Update deliberately after testing new versions in a staging environment.

OpenClaw follows semantic versioning. Major version updates may include breaking changes requiring configuration updates. Minor versions add features in backward-compatible ways. Patch versions contain bug fixes and security updates. Subscribe to release notifications on GitHub to stay informed about updates.

Rollback Procedure

If an update causes issues, rollback by specifying the previous version tag. Docker keeps previous image layers cached, making rollbacks fast. Maintain a record of your previously working version for easy rollback. Before updating, you might also create a volume backup to enable complete state restoration if needed.

This section addresses frequent issues encountered during Docker deployments and provides solutions. Most problems relate to permissions, networking, or configuration errors.

Container Won't Start

If the container exits immediately after starting, check the logs with docker logs openclaw. Common causes include permission errors on mounted volumes, invalid JSON in configuration files, or missing required environment variables. The logs typically indicate the specific issue.

For permission errors, verify the mounted directories are writable by UID 1000. On Linux, run chown -R 1000:1000 on your OpenClaw directories. On macOS and Windows with Docker Desktop, permissions are usually handled automatically but can require enabling file sharing in Docker settings.

Can't Access WebChat

If the container runs but you can't access the web interface, verify port mapping with docker port openclaw. Ensure no firewall rules block the ports. Try accessing via 127.0.0.1 instead of localhost. Check that the port isn't already in use by another application with netstat or lsof commands.

Channel Connection Issues

Messaging channel connections require the container to have internet access. Verify DNS resolution works within the container with docker exec openclaw nslookup google.com. Check that no proxy configuration is interfering with connections. Some corporate networks require additional proxy configuration.

WhatsApp connections are particularly sensitive to IP changes and container restarts. If WhatsApp disconnects frequently, ensure your container has a stable IP address and consider using host networking mode for more reliable connections.

High Memory Usage

OpenClaw's memory usage depends on conversation history length, number of active channels, and concurrent sessions. If memory usage seems excessive, check for memory leaks by monitoring container stats over time. The troubleshooting/memory-leaks guide provides detailed debugging procedures.

Set memory limits in your Docker configuration to prevent runaway memory consumption from affecting other services. The compose examples include memory limit configuration. OpenClaw functions well with 1GB memory limit for personal use, but increase this for multi-user deployments.