Self-Hosting OpenClaw: Complete Setup Guide

Self-hosting OpenClaw gives you full control over your AI coding assistant -- your data stays on your infrastructure, you choose the AI providers, and you set the rules. This guide covers the complete process from bare metal to a production-ready deployment.

Why Self-Host?

Before diving into the technical setup, it helps to understand what self-hosting buys you:

• Data sovereignty: All prompts, responses, and workspace files remain on your infrastructure
• Provider flexibility: Use any supported AI provider without intermediary services
• Cost control: Pay only for compute and AI API calls, with no platform markup
• Customization: Modify the deployment to fit your team's exact workflow

The trade-off is that you take on responsibility for uptime, updates, and security. For many teams, that trade-off is worth it.

System Requirements

OpenClaw is designed to run efficiently, but the gateway and AI processing do require reasonable resources.

Minimum Requirements

• CPU: 1 vCPU (2 recommended for concurrent users)
• RAM: 2 GB (4 GB recommended)
• Disk: 10 GB for the application and workspace data
• OS: Any Linux distribution with Docker support, or macOS/Windows with Docker Desktop
• Network: Outbound HTTPS access to your AI provider's API

Software Prerequisites

• Docker Engine 20.10 or newer
• Docker Compose v2 (optional but recommended)
• A domain name with DNS access (for production deployments)

Step 1: Clone the Repository

Start by cloning the OpenClaw Railway wrapper repository. Even if you're not deploying to Railway, this wrapper provides the setup wizard, reverse proxy, and lifecycle management that make running OpenClaw straightforward.

git clone https://github.com/your-org/openclaw-railway.git
cd openclaw-railway

Step 2: Build the Docker Image

The included Dockerfile handles the entire build process, compiling OpenClaw from source and installing the wrapper dependencies.

docker build -t openclaw-railway-template .

This multi-stage build takes a few minutes on the first run. Subsequent builds leverage Docker's layer cache and finish much faster.

Pinning a Specific Version

By default, the build uses the main branch of OpenClaw. For production stability, pin to a specific release:

docker build --build-arg OPENCLAW_GIT_REF=v2026.2.6 -t openclaw-railway-template .

Step 3: Prepare the Data Directory

OpenClaw stores its configuration and workspace files in a data directory. Create this on the host machine so data persists across container restarts:

mkdir -p /opt/openclaw/data

This directory will contain two subdirectories once the system is configured:

• .openclaw/ -- Configuration files, credentials, and session data
• workspace/ -- Agent workspace for file operations

Step 4: Run the Container

Launch OpenClaw with the required environment variables:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 8080:8080 \
  -e PORT=8080 \
  -e SETUP_PASSWORD=your-strong-password-here \
  -e OPENCLAW_STATE_DIR=/data/.openclaw \
  -e OPENCLAW_WORKSPACE_DIR=/data/workspace \
  -e OPENCLAW_GATEWAY_TOKEN=a-stable-random-token \
  -v /opt/openclaw/data:/data \
  openclaw-railway-template

Important Notes on Environment Variables

The OPENCLAW_GATEWAY_TOKEN variable deserves special attention. This token authenticates communication between the wrapper and the gateway. If you omit it, one will be generated automatically, but it will change on each fresh container start. Setting it explicitly ensures stable authentication across redeployments.

Generate a secure token with:

openssl rand -hex 32

Step 5: Complete the Setup Wizard

Open http://your-server:8080/setup in a browser. Enter your setup password and walk through the configuration wizard to select your AI provider and enter API credentials.

The wizard writes all configuration to the persistent data directory, so you only need to do this once.

Security Hardening

A default deployment works, but production use demands additional security measures.

Reverse Proxy with TLS

Never expose OpenClaw directly to the internet over plain HTTP. Place it behind a reverse proxy like Nginx or Caddy that terminates TLS:

server {
    listen 443 ssl;
    server_name openclaw.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/openclaw.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openclaw.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

The WebSocket upgrade headers are critical -- OpenClaw uses WebSockets for real-time communication with the gateway.

Firewall Rules

Restrict inbound access to ports 443 (HTTPS) and 22 (SSH for management). The OpenClaw container port (8080) should only be accessible from localhost.

Regular Backups

Use the built-in backup export feature at /setup/export to download a compressed archive of your configuration and workspace. Schedule this regularly using cron or your preferred automation tool.

Updating OpenClaw

To update your instance, rebuild the Docker image with the latest source and restart the container:

docker build --no-cache -t openclaw-railway-template .
docker stop openclaw
docker rm openclaw
# Re-run the docker run command from Step 4

Your configuration and workspace data persist in the mounted volume, so updates don't require reconfiguration.

Troubleshooting Common Issues

Gateway fails to start

Check the container logs with docker logs openclaw. Look for lines containing [gateway] to trace the startup sequence. The most common cause is a malformed openclaw.json file -- the backup export feature can help you save a known-good configuration.

WebSocket connections drop

This usually indicates a misconfigured reverse proxy. Ensure your proxy passes the Upgrade and Connection headers, and that timeout values are set high enough for long-running AI interactions.

High memory usage

If the container exceeds its memory limit, consider reducing concurrent session limits in the gateway configuration or upgrading your host's RAM allocation.

Conclusion

Self-hosting OpenClaw is straightforward once you understand the architecture. The Docker-based deployment handles the complex build process, the setup wizard manages configuration, and the wrapper takes care of authentication and proxying. With proper TLS termination and regular backups, you have a production-grade AI coding assistant running entirely on your own infrastructure.