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: 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

2

Set up a second (rescue) gateway

3

Install each as a service

​
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.
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:

​
Quick checks

Related: Gateway configuration · Doctor · Security hardening