Deployment Guide

This guide covers deploying OpenClaw gateway to production environments, from local development to cloud-hosted infrastructure.

Overview

OpenClaw gateway can be deployed in several modes:

Local machine — Your laptop/desktop (Mac, Linux, WSL2)
VPS/Bare metal — Dedicated servers (Hetzner, DigitalOcean, OVH)
Cloud platforms — Managed services (Fly.io, Railway, Render, GCP)
Container orchestration — Docker, Docker Compose, Kubernetes

System Requirements

Minimum Specifications

CPU: 1 core (2+ cores recommended for multiple agents)
RAM: 512 MB minimum, 1-2 GB recommended
Storage: 1 GB minimum, 5+ GB recommended for workspace and logs
Network: Stable internet connection, persistent IP recommended

Runtime Requirements

Node.js: 22+ (LTS recommended)
Optional: Docker for containerized deployments
Optional: Tailscale for secure remote access

Pre-Deployment Checklist

Before deploying to production:

Run security audit

openclaw security audit --deep

Run doctor checks

openclaw doctor

Test gateway locally

openclaw gateway --port 18789 --bind loopback

Verify authentication

openclaw config get gateway.auth.token
# or
echo $OPENCLAW_GATEWAY_TOKEN

Backup configuration

cp ~/.openclaw/config.json ~/.openclaw/config.json.backup

Deployment Options

Local Development

Ideal for:

Personal use
Development and testing
Single-user scenarios

Setup:

# Install globally
npm install -g openclaw@latest

# Run onboarding wizard
openclaw onboard --install-daemon

# Start gateway (daemon will auto-start on boot)
openclaw gateway --bind loopback

Configuration:

# ~/.openclaw/config.json
gateway:
  mode: local
  bind: loopback
  port: 18789
  auth:
    mode: token
    token: your-secure-token-here

VPS Deployment

Ideal for:

Always-on personal assistant
Remote access from multiple devices
Better uptime than local machine

Recommended Providers:

Hetzner

€4-20/month, excellent performance, EU-based

DigitalOcean

$6-40/month, simple setup, global regions

Linode

$5-40/month, strong support, predictable pricing

Vultr

$6-40/month, high-frequency compute options

VPS Setup (Ubuntu 22.04+):

# Update system
sudo apt update && sudo apt upgrade -y

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install OpenClaw
sudo npm install -g openclaw@latest

# Create openclaw user
sudo useradd -m -s /bin/bash openclaw
sudo -u openclaw bash

# Run onboarding as openclaw user
openclaw onboard --install-daemon

# Start gateway with systemd (auto-enabled by onboard)
sudo systemctl --user enable openclaw-gateway
sudo systemctl --user start openclaw-gateway

Networking:

# For LAN-only access
openclaw config set gateway.bind loopback

# For remote access with Tailscale (recommended)
openclaw config set gateway.bind tailnet

# For remote access via public IP (requires strong auth)
openclaw config set gateway.bind lan
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"

Fly.io Deployment

Ideal for:

Global edge deployment
Auto-scaling
Managed infrastructure

From source repository: The included fly.toml configures:

2GB RAM, 2 shared CPUs
Persistent volume for state
HTTPS with automatic certificates
Auto-restart on failure

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login
fly auth login

# Create app (in openclaw repo directory)
fly apps create openclaw-gateway

# Create volume for persistent state
fly volumes create openclaw_data --size 1 --region iad

# Set secrets
fly secrets set OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
fly secrets set CLAUDE_AI_SESSION_KEY="your-session-key"

# Deploy
fly deploy

# Check status
fly status
fly logs

Configuration (fly.toml):

app = "openclaw-gateway"
primary_region = "iad"  # Change to your region

[build]
  dockerfile = "Dockerfile"

[env]
  NODE_ENV = "production"
  OPENCLAW_PREFER_PNPM = "1"
  OPENCLAW_STATE_DIR = "/data"
  NODE_OPTIONS = "--max-old-space-size=1536"

[processes]
  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = false
  min_machines_running = 1

[[vm]]
  size = "shared-cpu-2x"
  memory = "2048mb"

[mounts]
  source = "openclaw_data"
  destination = "/data"

Railway Deployment

Ideal for:

Simple one-click deployment
Automatic builds from GitHub
Integrated database options

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Create project
railway init

# Set environment variables
railway variables set OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"
railway variables set PORT=8080

# Deploy
railway up

Render Deployment

Ideal for:

Managed Docker hosting
Free tier available
Auto-deploy from Git

From source render.yaml:

services:
  - type: web
    name: openclaw
    runtime: docker
    plan: starter
    healthCheckPath: /health
    envVars:
      - key: PORT
        value: "8080"
      - key: OPENCLAW_GATEWAY_TOKEN
        generateValue: true
      - key: OPENCLAW_STATE_DIR
        value: /data/.openclaw
    disk:
      name: openclaw-data
      mountPath: /data
      sizeGB: 1

Fork OpenClaw repository
Connect to Render dashboard
Create “New Web Service” from repo
Render auto-detects render.yaml
Deploy!

Google Cloud Platform

Ideal for:

Enterprise deployments
Integration with GCP services
Custom VM configurations

Cloud Run deployment:

# Build and push image
gcloud builds submit --tag gcr.io/PROJECT_ID/openclaw

# Deploy to Cloud Run
gcloud run deploy openclaw-gateway \
  --image gcr.io/PROJECT_ID/openclaw \
  --platform managed \
  --region us-central1 \
  --memory 2Gi \
  --cpu 2 \
  --set-env-vars OPENCLAW_GATEWAY_TOKEN=your-token

Environment Variables

Critical environment variables for production:

Variable	Description	Required
`OPENCLAW_GATEWAY_TOKEN`	Authentication token	Yes (if using token auth)
`OPENCLAW_GATEWAY_PASSWORD`	Authentication password	Yes (if using password auth)
`CLAUDE_AI_SESSION_KEY`	Claude API session key	Yes (for Claude provider)
`CLAUDE_WEB_SESSION_KEY`	Claude web session	Optional
`OPENCLAW_STATE_DIR`	State directory path	Optional (default: `~/.openclaw`)
`OPENCLAW_WORKSPACE_DIR`	Workspace directory	Optional
`NODE_ENV`	Node environment	Optional (default: `production`)
`PORT`	Gateway port	Optional (default: 18789)

Health Checks

Monitor gateway health:

# Local health check
curl http://localhost:18789/health

# With authentication
curl -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
     http://localhost:18789/health

# CLI health check
openclaw doctor
openclaw channels status --probe

Persistence and State

OpenClaw stores state in:

Config: ~/.openclaw/config.json
Sessions: ~/.openclaw/agents/<agent-id>/sessions/
Workspace: ~/.openclaw/workspace/ (default)
Credentials: ~/.openclaw/credentials/
Logs: Platform-specific (systemd journal, Docker logs)

Backup strategy:

# Backup entire state directory
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# Restore from backup
tar -xzf openclaw-backup-20260219.tar.gz -C ~/

Platform-Specific Notes

Linux (systemd)

The onboarding wizard installs a systemd user service:

# Service management
systemctl --user status openclaw-gateway
systemctl --user restart openclaw-gateway
systemctl --user stop openclaw-gateway

# View logs
journalctl --user -u openclaw-gateway -f

# Enable linger (keeps service running after logout)
sudo loginctl enable-linger $USER

macOS (launchd)

Gateway runs as a LaunchAgent:

# Via OpenClaw app
# Start/stop from menu bar

# Manual control
launchctl list | grep openclaw
./scripts/restart-mac.sh

Docker Considerations

Ensure volume mounts for persistence:

/home/node/.openclaw for state
/home/node/.openclaw/workspace for workspace files

See Docker Guide for detailed Docker setup.

Updating Production Deployments

VPS Update

# Stop gateway
systemctl --user stop openclaw-gateway

# Backup config
cp ~/.openclaw/config.json ~/.openclaw/config.json.backup

# Update
npm install -g openclaw@latest

# Run doctor
openclaw doctor

# Restart
systemctl --user start openclaw-gateway

Cloud Platform Updates

Fly.io: fly deploy (rebuilds from Dockerfile)
Railway: Push to connected Git branch
Render: Auto-deploys on Git push
GCP Cloud Run: Re-run gcloud run deploy

Next Steps

Docker Setup

Containerized deployment with Docker Compose

Security Guide

Secure your gateway with best practices

Troubleshooting

Common issues and solutions

Multi-Agent Setup

Route channels to isolated agents

Getting Started

Core Concepts

Channels

Platform Apps

Guides

Deployment Guide

Deployment Guide

Overview

System Requirements

Minimum Specifications

Runtime Requirements

Pre-Deployment Checklist

Deployment Options

Local Development

VPS Deployment

Hetzner

DigitalOcean

Linode

Vultr

Fly.io Deployment

Railway Deployment

Render Deployment

Google Cloud Platform

Environment Variables

Health Checks

Persistence and State

Platform-Specific Notes

Linux (systemd)

macOS (launchd)

Docker Considerations

Updating Production Deployments

VPS Update

Cloud Platform Updates

Next Steps

Docker Setup

Security Guide

Troubleshooting

Multi-Agent Setup

Getting Started

Core Concepts

Channels

Platform Apps

Guides

Documentation Index

​Deployment Guide

​Overview

​System Requirements

​Minimum Specifications

​Runtime Requirements

​Pre-Deployment Checklist

​Deployment Options

​Local Development

​VPS Deployment

Hetzner

DigitalOcean

Linode

Vultr

​Fly.io Deployment

​Railway Deployment

​Render Deployment

​Google Cloud Platform

​Environment Variables

​Health Checks

​Persistence and State

​Platform-Specific Notes

​Linux (systemd)

​macOS (launchd)

​Docker Considerations

​Updating Production Deployments

​VPS Update

​Cloud Platform Updates

​Next Steps

Docker Setup

Security Guide

Troubleshooting

Multi-Agent Setup

Deployment Guide

Overview

System Requirements

Minimum Specifications

Runtime Requirements

Pre-Deployment Checklist

Deployment Options

Local Development

VPS Deployment

Fly.io Deployment

Railway Deployment

Render Deployment

Google Cloud Platform

Environment Variables

Health Checks

Persistence and State

Platform-Specific Notes

Linux (systemd)

macOS (launchd)

Docker Considerations

Updating Production Deployments

VPS Update

Cloud Platform Updates

Next Steps