OpenClaw

Deploying OpenClaw to Production👨‍💻

Taking OpenClaw from a local development setup to a reliable production deployment involves five concerns: containerization (Docker), process management (pm2 or systemd), reverse proxy with TLS (Caddy or Nginx), health monitoring, and scaling strategy. OpenClaw runs as a single Node.js process, which makes deployment simpler than distributed systems but requires careful attention to persistence, restart policies, and resource limits. This page provides production-ready configurations for each concern, from a minimal Docker Compose setup to a full monitoring stack.

Key Takeaways

  • 1Docker is the recommended deployment method. The official OpenClaw image includes Node.js 22 and all dependencies. Mount openclaw.json as read-only and the agents directory as a persistent volume. Use docker-compose for single-server deployments.
  • 2A reverse proxy (Caddy or Nginx) is mandatory for production. It handles TLS termination (HTTPS), rate limiting, request size limits, and domain routing. Never expose the Gateway port (18789) directly to the internet.
  • 3Process managers ensure the Gateway restarts after crashes and persists across reboots. Docker's restart: unless-stopped policy handles this in containerized deployments. For bare-metal, use pm2 with `pm2 startup` or a systemd service unit.
  • 4Health checks are essential for automated recovery. The Gateway exposes a `/health` endpoint that returns JSON with status, uptime, active channels, and agent count. Configure Docker HEALTHCHECK, Kubernetes probes, or external monitoring to poll this endpoint.
  • 5The agents directory (`~/.openclaw/agents/`) must be persisted across deploys and container recreations. It contains irreplaceable data: SOUL.md files, MEMORY.md, session history, and skill installations. Always use a Docker volume or bind mount.
  • 6OpenClaw is a single-process architecture. Scaling horizontally with multiple replicas creates independent gateways with separate state. For high availability, use liveness probes with auto-restart rather than multiple replicas. For high throughput, deploy separate gateways per channel or domain.

Master deploying openclaw to production

Take the OpenClaw for Production & Advanced Use course with hands-on lessons and challenges.

Examples

Production Docker Compose with Caddy reverse proxy

yaml

This production setup runs the Gateway and Caddy reverse proxy as separate containers on an internal network. Only Caddy exposes ports 80/443 to the internet -- the Gateway is not directly accessible. The agents directory is persisted in a Docker volume. Resource limits prevent the Gateway from consuming all host memory. The health check restarts the container after 3 consecutive failures.

Caddy and Nginx reverse proxy configurations

bash

Caddy is simpler because it auto-provisions TLS certificates from Let's Encrypt with zero configuration. Nginx is more flexible but requires manual TLS setup with certbot. Both configurations include rate limiting and request size limits. The Nginx config includes WebSocket support headers, which are required if you use the webchat channel.

Bare-metal deployment with pm2 and systemd

bash

For bare-metal deployments without Docker, pm2 or systemd keep the Gateway running. pm2 is simpler and includes a monitoring dashboard. Systemd is the standard Linux service manager and integrates with journalctl for log management. Both restart the Gateway automatically after crashes and on system reboots. The systemd unit runs as a dedicated user with elevated file descriptor limits.

Health monitoring and alerting setup

bash

The /health endpoint provides comprehensive system status including per-channel and per-agent counts, active sessions, and memory usage. External monitoring services should poll this endpoint every 30 seconds. The stats command provides 24-hour aggregates for capacity planning. Monitor for channel disconnects, which indicate network or token issues with messaging platforms.

Backup and disaster recovery

bash

The agents directory is the most critical data to back up. It contains SOUL.md personas, MEMORY.md accumulated knowledge, session history, and installed skills -- all irreplaceable. This script backs up everything daily, compresses it, and retains 30 days. Add it to cron with `0 2 * * * /opt/openclaw/backup.sh` to run at 2 AM daily.

Common Mistakes

Mistake:

Exposing the Gateway port (18789) directly to the internet without a reverse proxy, missing TLS encryption, rate limiting, and request size limits

Fix:

Always place Caddy, Nginx, or a cloud load balancer in front of the Gateway. The reverse proxy provides TLS, rate limiting, and WebSocket support. The Gateway port should only be accessible on localhost or an internal network.

Mistake:

Not persisting the agents directory, losing all SOUL.md files, MEMORY.md, session history, and installed skills when the container is recreated

Fix:

Mount the agents directory as a Docker volume or bind mount. This is the most critical data in the entire deployment. Without persistence, every container restart wipes all agent knowledge and configuration.

Mistake:

Running the Gateway without resource limits, allowing a memory leak or runaway process to consume all host resources and crash other services

Fix:

Set memory and CPU limits in Docker Compose (deploy.resources.limits) or systemd (MemoryLimit, CPUQuota). A 2GB memory limit and 2 CPU cores is sufficient for most deployments.

Mistake:

Setting Docker replicas or Kubernetes replicas to more than 1, expecting horizontal scaling, when the Gateway maintains in-memory session state

Fix:

OpenClaw is a single-process architecture with in-memory state. Multiple replicas create independent gateways with separate sessions. For high availability, use liveness probes and auto-restart. For throughput, deploy separate gateways per channel.

Mistake:

Not configuring WebSocket support in the reverse proxy, causing the webchat channel to fail with connection timeout errors

Fix:

Add WebSocket upgrade headers to your Nginx configuration (proxy_http_version 1.1, Upgrade, Connection headers). Caddy handles WebSocket proxying automatically. Test with a WebSocket client before deploying.

Best Practices

  • Use Docker Compose with Caddy for most deployments. This two-service setup provides containerization, auto-TLS, rate limiting, and health checks with minimal configuration.
  • Always persist the agents directory. Use a Docker named volume (not a bind mount to a temporary location). Include it in your backup strategy and test restoration periodically.
  • Set resource limits (memory: 2G, cpus: 2.0) to prevent resource exhaustion. Monitor heap usage via the /health endpoint and adjust limits based on actual usage patterns.
  • Configure health checks with appropriate intervals (30s), timeouts (10s), and retries (3). Set a start_period (15s) to give the Gateway time to initialize before health checks begin.
  • Set up external monitoring (UptimeRobot, Datadog, Prometheus) that polls the /health endpoint from outside your network. Internal health checks catch process failures; external monitoring catches network-level issues.
  • Maintain separate configurations for staging and production. Staging uses test channel tokens, cheaper models, and relaxed security. Production uses real credentials, strict sandboxing, and rate limiting.

Summary

Deploying OpenClaw to production requires Docker with a reverse proxy (Caddy or Nginx) for TLS and rate limiting, persistent storage for the agents directory, health checks for automated recovery, resource limits to prevent exhaustion, and external monitoring. Use Docker Compose with Caddy for the simplest production setup. Never expose the Gateway port directly. Persist the agents directory -- it contains irreplaceable data. OpenClaw is single-process; scale by deploying separate gateways per channel, not by adding replicas. Back up daily and test restoration.

Practice OpenClaw with hands-on challenges

Learn deploying openclaw to production hands-on in your IDE

Interactive lessons and challenges on Stanza, practice in VS Code, Cursor, or the web.

Related Concepts

Openclaw DeploymentOpenclaw Security HardeningOpenclaw Security SandboxingOpenclaw GatewayOpenclaw Agents

Related Cheatsheets

Openclaw Cli Cheatsheet

Master OpenClaw with Stanza

Interactive lessons and challenges, right in your code editor.

Check the free courses. No credit card.