Skip to main content

​
Multi-gateway setup

Most deployments should run a single gateway. One gateway can handle many channels and many agents at once, so a second instance is rarely needed. You only need multiple gateways for stronger isolation or redundancy — for example a separate “rescue” bot that can debug or repair the main bot while it is down, or hard trust separation between two boundaries on the same machine.
For mixed-trust or adversarial-user separation, prefer separate OS users or hosts over multiple gateways on one host. See Security hardening.

​
Isolation checklist

Every gateway instance on the same host must have its own:
SettingPurpose
OPENCLAW_CONFIG_PATHPer-instance config file
OPENCLAW_STATE_DIRPer-instance sessions, credentials, and caches
agents.defaults.workspacePer-instance workspace root
gateway.port (or --port)Unique base port
Derived ports (browser, canvas, CDP)Must not overlap between instances
If any of these are shared, you will hit config races and port conflicts. The --profile flag is the simplest path. A profile auto-scopes OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH, and suffixes the installed service name so each instance gets its own systemd/launchd unit.
1

Set up the main gateway

openclaw --profile main setup
openclaw --profile main gateway --port 18789
2

Set up a second (rescue) gateway

openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001
3

Install each as a service

openclaw --profile main gateway install
openclaw --profile rescue gateway install

​
Rescue-bot pattern

A rescue bot is a second gateway on the same host with its own profile, config, state directory, workspace, and base port. Keeping it isolated means it can still respond and apply config changes even if the primary bot is wedged. 
# Main bot (no --profile; runs on 18789 plus derived ports)
openclaw onboard
openclaw gateway install

# Rescue bot (isolated profile + ports)
openclaw --profile rescue onboard
# - workspace name is suffixed with -rescue by default
# - pick a clearly separated base port, e.g. 19789
openclaw --profile rescue gateway install
Leave at least 20 ports between base ports so the derived browser, canvas, and CDP ports never collide.

​
Derived ports

The base port is gateway.port (or OPENCLAW_GATEWAY_PORT / --port). Other services derive from it:
  • Browser control service port = base + 2 (loopback only)
  • Canvas host is served on the gateway HTTP server (same port as gateway.port)
  • Browser profile CDP ports auto-allocate from browser.controlPort + 9 through + 108
If you override any of these in config or env, keep them unique per instance.
Browser/CDP footgun. Do not pin browser.cdpUrl to the same value on multiple instances. Each instance needs its own browser control port and CDP range. For explicit ports, set browser.profiles.<name>.cdpPort per instance; for remote Chrome, use browser.profiles.<name>.cdpUrl per profile, per instance.

​
Manual environment variables

If you prefer not to use profiles, set the isolation variables explicitly per instance: 
OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
OPENCLAW_STATE_DIR=~/.openclaw-main \
openclaw gateway --port 18789

OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
OPENCLAW_STATE_DIR=~/.openclaw-rescue \
openclaw gateway --port 19001

​
Quick checks

openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status
Related: Gateway configuration · Doctor · Security hardening