Multiple Gateways Setup Guide

Most deployments require just one Gateway, since a single instance can handle multiple messaging connections and agents. Only spin up separate Gateways with isolated profiles or ports when you need stronger isolation or redundancy, such as a rescue bot.

Rescue-bot quickstart

The minimal rescue-bot configuration looks like this:

Leave the primary bot on its default profile.
Launch the rescue bot with --profile rescue, using a dedicated Telegram bot token.
Assign the rescue bot a different base port, for instance 19789.

That way, the rescue bot can still debug or apply config changes when the main bot is offline. Keep at least 20 ports of separation between base ports so derived browser/CDP ports never overlap.

# Rescue bot (separate Telegram bot, separate profile, port 19789)
openclaw --profile rescue onboard
openclaw --profile rescue gateway install --port 19789

If your primary bot is already active, this is typically all you need. When onboarding already set up the rescue service, omit the final gateway install.

During openclaw --profile rescue onboard:

Use a separate Telegram bot token for the rescue account, which keeps it operator-only, independent from the main bot's channel or app install, and gives a straightforward DM-based recovery route.
Stick with the rescue profile name.
Pick a base port at least 20 higher than the main bot's.
Accept the default rescue workspace unless you already manage one.

What `--profile rescue onboard` changes

--profile rescue onboard follows the normal onboarding flow but writes everything into a distinct profile, giving the rescue bot its own:

Profile/config file
State directory
Workspace (defaults to ~/.openclaw/workspace-rescue)
Managed service name
Base port (plus derived ports)
Telegram bot token

Prompts match normal onboarding otherwise.

General multi-gateway setup

The same isolation approach applies to any pair or group of Gateways on a single host: give each extra Gateway its own named profile and base port.

# main (default profile)
openclaw setup
openclaw gateway --port 18789

# extra gateway
openclaw --profile ops setup
openclaw --profile ops gateway --port 19789

Named profiles work on both sides as well:

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

openclaw --profile ops setup
openclaw --profile ops gateway --port 19789

Services follow the identical pattern:

openclaw gateway install
openclaw --profile ops gateway install --port 19789

Use the rescue-bot quickstart for a fallback operator lane; use the general profile pattern for multiple long-lived Gateways across different channels, tenants, workspaces, or operational roles.

Isolation checklist

Keep these unique per Gateway instance:

Setting	Purpose
`OPENCLAW_CONFIG_PATH`	Per-instance config file
`OPENCLAW_STATE_DIR`	Per-instance sessions, creds, caches
`agents.defaults.workspace`	Per-instance workspace root
`gateway.port` (or `--port`)	Unique per instance
Derived browser/CDP ports	See below

Sharing any of these leads to config, state, or port conflicts. Gateway startup enforces unique state-directory ownership even when OPENCLAW_ALLOW_MULTI_GATEWAY=1 skips the per-config singleton.

Port mapping (derived)

Base port = gateway.port (or OPENCLAW_GATEWAY_PORT / --port).

Browser control service port = base + 2 (loopback only).
Hosted widget documents and A2UI renderer assets are served on the Gateway HTTP server itself (same port as gateway.port).
Browser profile CDP ports auto-allocate from browser control port + 9 through + 108.

Override any of these in config or env and you must keep them unique per instance.

Browser/CDP notes (common footgun)

Do not pin browser.cdpUrl to the same value on multiple instances.
Each instance needs its own browser control port and CDP range (derived from its gateway port).
For explicit CDP ports, set browser.profiles.<name>.cdpPort per instance.
For remote Chrome, use browser.profiles.<name>.cdpUrl (per profile, per instance).

Manual env example

OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
OPENCLAW_STATE_DIR=~/.openclaw \
openclaw gateway --port 18789

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

Quick checks

openclaw gateway status --deep
openclaw --profile rescue gateway status --deep
openclaw --profile rescue gateway probe
openclaw status
openclaw --profile rescue status
openclaw --profile rescue browser status

gateway status --deep catches stale launchd/systemd/schtasks services from older installs.
gateway probe warning text such as multiple reachable gateway identities detected is expected only when you intentionally run more than one isolated gateway, or when OpenClaw cannot prove reachable probe targets are the same gateway. An SSH tunnel, proxy URL, or configured remote URL to the same gateway is one gateway with multiple transports, even when transport ports differ.