Self-Hosted Architecture

+15 Mana ✨
OpenClaw Deployment Guide(DOCUMENTATION)OpenClaw Configuration Reference(DOCUMENTATION)

Introduction

OpenClaw runs entirely on your own hardware or cloud infrastructure as a single Gateway process. This self-hosted design means you never send your conversations, credentials, or agent logic through a third-party service. Understanding where each component runs and why this matters is essential for deploying OpenClaw effectively.

Key Concepts

  • Single Gateway Process: One long-running Node.js process that handles all message routing, channel connections, and agent dispatching
  • Data Ownership: All messages, sessions, and agent memory stay on your infrastructure
  • Zero Cloud Dependencies: No mandatory external services, SaaS subscriptions, or vendor APIs required by the gateway itself
  • Deployment Flexibility: Run on a Raspberry Pi, a VPS, a Kubernetes cluster, or bare metal

Real World Context

Consider a healthcare startup building an AI assistant that answers patient questions over WhatsApp. Data privacy regulations like HIPAA and GDPR require strict control over where patient data is stored and processed. A hosted messaging service would introduce compliance risks. With OpenClaw, the entire message pipeline runs within the startup's own infrastructure, making compliance audits straightforward and giving the team full visibility into data flows.

Deep Dive

The OpenClaw Gateway is a single Node.js process. This is a deliberate architectural choice. Instead of a distributed microservices mesh, OpenClaw keeps things simple: one process, one configuration, one deployment unit.

Here is what a typical deployment looks like at the system level:

bash
# Check your Node.js version (must be 22+)
node --version

# Start the Gateway
openclaw gateway

The first command verifies your Node.js version. The second command starts the Gateway process, which reads its configuration from ~/.openclaw/openclaw.json and begins listening on the default port (18789).

The Gateway process manages several responsibilities internally:

  • Channel Adapters: Each connected chat platform has an adapter that handles authentication, webhook registration, and message format translation
  • Message Router: Determines which agent should handle an incoming message based on session context, channel rules, or workspace configuration
  • Agent Runtime: Executes your agent logic, managing tool calls, memory retrieval, and response generation
  • Session Store: Maintains conversation state so agents can carry context across multiple messages

All of these run inside the same process. Here is a minimal configuration file that illustrates the structure:

json
{
  "gateway": {
    "port": 18789
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}"
    },
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}"
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic:claude-sonnet-4-20250514"
      }
    }
  }
}

This configuration tells the Gateway to listen on port 18789, connect to Telegram and Discord using bot tokens stored in environment variables, and route all messages to a default agent using Claude Sonnet. The tokens are never sent anywhere except directly to the respective platform APIs from your own machine.

To run OpenClaw as a persistent background service, you can use a process manager:

bash
# Using pm2 as a process manager
pm2 start openclaw -- gateway

# Check status
pm2 status

# View logs
pm2 logs openclaw

The pm2 start command wraps the OpenClaw process so it restarts automatically if it crashes and persists across system reboots. The pm2 status command shows whether the Gateway is running, and pm2 logs streams the process output for debugging.

Common Pitfalls

  • Forgetting to open firewall ports: Channels like Telegram require webhook callbacks. Your server must be reachable on the configured port for incoming webhooks to work.
  • Running without a process manager in production: Starting OpenClaw directly in a terminal means it stops when the terminal closes. Always use a process manager like pm2 or systemd for production deployments.
  • Using environment variables without a secrets manager: Hardcoding tokens in configuration files is risky. Use environment variable references or a secrets manager.

Best Practices

  • Use environment variables for all secrets: Never commit bot tokens or API keys to version control. Reference them with ${VAR_NAME} syntax in your config.
  • Run behind a reverse proxy: Place Nginx or Caddy in front of the Gateway to handle TLS termination, rate limiting, and domain routing.
  • Monitor the Gateway process: Set up health checks and alerting so you know immediately if the process crashes or becomes unresponsive.

Summary

  • OpenClaw runs as a single Gateway process on your own infrastructure, with no mandatory cloud dependencies
  • The process handles channel adapters, message routing, agent runtime, and session storage internally
  • Configuration is done through a single JSON file that references environment variables for secrets
  • A process manager like pm2 ensures the Gateway stays running in production
  • Self-hosting gives you full data ownership, privacy compliance, and deployment flexibility
✓ Completed