🎯 OpenClaw Project Overview

OpenClaw is an asynchronous high‑performance web framework built with Rust, designed for cloud‑native environments. Core features:

⚡ Extreme Performance

Based on the tokio async runtime, zero‑cost abstractions, memory safe with no GC. Handles 100k+ concurrent connections per node.

🔒 Enterprise Security

Built‑in SQL injection protection, XSS filtering, CSRF tokens, rate limiting – meets OWASP Top 10.

☁️ Cloud‑Native Ready

Native Prometheus metrics, health checks, distributed tracing; works with K8s, EC2, Lighthouse.

📋 Environment & Dependencies

System Requirements

Linux (Ubuntu 20.04+/Debian 11+/CentOS 8+)
macOS 12+ (Intel/Apple Silicon)
Windows 10+ (WSL2 recommended)
2GB+ RAM, 10GB+ disk

Toolchain Installation

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source $HOME/.cargo/env
rustup default stable

# Install system dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev git

# Install Docker (optional)
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

💡 Version requirements: Rust 1.70+, PostgreSQL 12+, Redis 6+, Docker 20.10+

💻 Local Development Setup

1 Get the source

git clone https://github.com/openclaw/openclaw.git
cd openclaw
git checkout v1.2.0

2 Configure environment variables

Copy the environment template:

cp .env.example .env

Edit the core settings in .env:

# Application config
APP_NAME=openclaw
APP_ENV=development
APP_HOST=0.0.0.0
APP_PORT=8080

# PostgreSQL database
DATABASE_URL=postgres://openclaw:password@localhost:5432/openclaw

# Redis cache
REDIS_URL=redis://localhost:6379

# JWT authentication secret
JWT_SECRET="$(openssl rand -base64 32)"

3 Database migrations

# Install SQLx CLI
cargo install sqlx-cli --no-default-features --features native-tls,postgres

# Create and migrate database
sqlx database create
sqlx migrate run

4 Build and run

# Development mode (with hot‑reload)
cargo install cargo-watch
cargo watch -x run

# Production build
cargo build --release
./target/release/openclaw

✅ Verify deployment: Visit http://localhost:8080/health – should return {"status":"healthy"}

🐳 Docker Containerization

Multi‑stage Dockerfile

# Build stage
FROM rust:1.70-slim-bullseye AS builder
WORKDIR /app
COPY . .
RUN apt-get update && apt-get install -y pkg-config libssl-dev
RUN cargo build --release

# Runtime stage
FROM debian:bullseye-slim
RUN apt-get update && apt-get install -y ca-certificates libssl1.1 && rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/openclaw /usr/local/bin/
ENV APP_ENV=production
EXPOSE 8080
CMD ["openclaw"]

Full‑stack Docker Compose

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_DB: openclaw
      POSTGRES_USER: openclaw
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U openclaw"]
      
  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
      
  openclaw:
    build: .
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgres://openclaw:${DB_PASSWORD}@postgres:5432/openclaw
      REDIS_URL: redis://redis:6379
      JWT_SECRET: ${JWT_SECRET}
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started

volumes:
  postgres_data:
  redis_data:

# Start services
docker-compose up -d
# View logs
docker-compose logs -f openclaw

☸️ Kubernetes Production Deployment

Manifest (Deployment + Service + Ingress)

# openclaw-k8s.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: openclaw
  namespace: default
spec:
  replicas: 3
  selector:
    matchLabels:
      app: openclaw
  template:
    metadata:
      labels:
        app: openclaw
    spec:
      containers:
      - name: openclaw
        image: openclaw/openclaw:1.2.0
        ports:
        - containerPort: 8080
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: openclaw-secret
              key: database-url
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: openclaw-service
spec:
  selector:
    app: openclaw
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

# Create secret
kubectl create secret generic openclaw-secret \
  --from-literal=database-url=postgres://user:pass@postgres:5432/openclaw

# Deploy
kubectl apply -f openclaw-k8s.yaml

# Rolling update
kubectl set image deployment/openclaw openclaw=openclaw/openclaw:1.2.1

☁️ One‑Click Cloud Deployment

🚀 Tencent Cloud Lighthouse

Official marketplace image – one‑click deploy with PostgreSQL/Redis pre‑installed, auto HTTPS, live in 3 minutes.

⚡ AWS ECS

Fargate serverless containers, auto‑scaling, deep integration with CloudWatch.

🔷 Google Cloud Run

Knative‑based serverless container, pay‑per‑request, multi‑region deployment.

📘 Azure AKS

Managed Kubernetes with Azure Monitor and Entra ID authentication.

📊 Monitoring & Operations

Prometheus Metrics Integration

use prometheus::{Encoder, TextEncoder, register_counter, Counter};
use lazy_static::lazy_static;

lazy_static! {
    static ref HTTP_REQUESTS: Counter = register_counter!(
        "http_requests_total",
        "Total number of HTTP requests"
    ).unwrap();
}

async fn metrics_handler() -> impl Responder {
    let encoder = TextEncoder::new();
    let mut buffer = vec![];
    encoder.encode(&prometheus::gather(), &mut buffer).unwrap();
    
    HttpResponse::Ok()
        .content_type("text/plain; version=0.0.4")
        .body(buffer)
}

Health Check Endpoints

Endpoint	Expected response	Usage
`/health`	200 + {"status":"healthy"}	K8s livenessProbe
`/ready`	200 + {"ready":true}	K8s readinessProbe
`/metrics`	200 + Prometheus format	Monitoring
`/version`	200 + {"version":"1.2.0"}	Version management

🔧 Common Troubleshooting

❌ Database connection pool exhausted

Symptom: Logs show pool timed out while waiting for connection

Solution:

# Increase pool size
DATABASE_POOL_SIZE=30
DATABASE_TIMEOUT=30

# Enable connection reuse
DATABASE_CONNECTIONS_MAX_LIFETIME="1800s"

❌ Memory keeps growing

Symptom: RSS memory increases linearly with requests, never released