Multiple Gateways

+15 Mana ✨
OpenClaw Multiple Gateways(DOCUMENTATION)

Introduction

OpenClaw supports running multiple gateway instances on the same machine or across machines. Each gateway has its own port, configuration, state directory, and set of agents. This pattern enables workload isolation, team separation, and high availability through redundancy.

Key Concepts

  • Gateway Instance: A single OpenClaw process with its own configuration and state. Multiple instances can run concurrently.
  • Port Isolation: Each gateway must listen on a unique port to avoid conflicts.
  • State Directory Isolation: Each gateway uses a separate state directory to prevent data collisions.
  • Workload Isolation: Different gateways handle different teams, environments, or use cases.

Real World Context

A company runs two gateways: one for production agents serving customers (port 18789, high reliability) and one for development agents used by engineers (port 18790, experimental). If the dev gateway crashes while testing a new agent configuration, the production gateway is unaffected.

Deep Dive

Run multiple gateways with different configurations:

bash
# Production gateway
OPENCLAW_HOME=~/.openclaw-prod openclaw gateway --port 18789

# Development gateway
OPENCLAW_HOME=~/.openclaw-dev openclaw gateway --port 18790

The OPENCLAW_HOME environment variable sets the state directory. Each gateway reads its configuration from its own home directory and stores sessions, memory, and credentials independently.

Alternatively, use the --config flag:

bash
# Production gateway with explicit config
openclaw gateway --config /etc/openclaw/prod.json --port 18789

# Staging gateway
openclaw gateway --config /etc/openclaw/staging.json --port 18790

Each config file defines its own agents, channels, and settings.

With Docker Compose, run multiple gateways as separate services:

yaml
services:
  gateway-prod:
    image: openclaw/gateway:2026.2.19
    ports: ["18789:18789"]
    volumes: ["prod-data:/root/.openclaw"]
  gateway-dev:
    image: openclaw/gateway:2026.2.19
    ports: ["18790:18789"]
    volumes: ["dev-data:/root/.openclaw"]

volumes:
  prod-data:
  dev-data:

Each service has its own volume, ensuring complete isolation.

Common Pitfalls

  1. Port conflicts — Two gateways on the same port causes one to fail on startup. Always use unique ports.
  2. Shared state directories — Two gateways sharing ~/.openclaw will corrupt each other's data. Always use separate state directories.

Best Practices

  1. Use naming conventions — Name state directories and Docker volumes consistently: openclaw-prod, openclaw-staging, openclaw-dev.
  2. Monitor each gateway independently — Set up separate health checks and alerts for each gateway instance.

Summary

  • Multiple gateways can run concurrently with unique ports and state directories
  • OPENCLAW_HOME environment variable isolates state per gateway
  • Docker Compose manages multiple gateways as separate services with isolated volumes
  • Use multiple gateways for workload isolation between production and development
  • Never share state directories between gateway instances
✓ Completed