Multiple Gateways Setup

Most deployments require only a single Gateway, which can handle numerous messaging connections and agents simultaneously. Running multiple Gateways with separate profiles and ports is only necessary when you need greater isolation or redundancy, for example a rescue bot.

Rescue-bot quickstart

A basic rescue bot configuration looks like this:

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

This arrangement allows the rescue bot to perform debugging or configuration changes if the primary bot becomes unavailable. Ensure at least 20 ports separate the base ports so that derived browser and 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 main bot is already active, this setup is typically sufficient. If the onboarding process already installed the rescue service, you can omit the final gateway install.

During openclaw --profile rescue onboard:

Provide a separate Telegram bot token specifically for the rescue account. This makes it straightforward to restrict access to operators only, keeps it independent from the main bot's channel or app installation, and offers a simple recovery path through direct messages.
Retain the rescue profile name.
Choose a base port that is at least 20 higher than the main bot's.
Accept the default rescue workspace unless you already manage one yourself.

What `--profile rescue onboard` changes

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

Profile and config file
State directory
Workspace, which defaults to ~/.openclaw/workspace-rescue
Managed service name
Base port along with derived ports
Telegram bot token

The prompts are otherwise identical to those in normal onboarding.

General multi-gateway setup

This isolation approach works for any pair or group of Gateways on a single host. Give each additional 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 on both sides also work.

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

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

Services follow the same pattern.

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

Use the rescue bot quickstart for a fallback operator channel. Use the general profile pattern for multiple long running Gateways across different channels, tenants, workspaces, or operational roles.

Isolation checklist

Keep these settings unique per Gateway instance:

Setting	Purpose
`OPENCLAW_CONFIG_PATH`	Per instance config file
`OPENCLAW_STATE_DIR`	Per instance sessions, credentials, 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 conflicts with configuration, state, or ports. Gateway startup enforces unique state directory ownership even when OPENCLAW_ALLOW_MULTI_GATEWAY=1 skips the per config singleton.

Port mapping (derived)

Base port equals gateway.port (or OPENCLAW_GATEWAY_PORT or --port).

The browser control service port is base plus 2, and is loopback only.
The Canvas host is served on the Gateway HTTP server itself, on the same port as gateway.port.
Browser profile CDP ports auto allocate from browser control port + 9 through + 108.

If you override any of these in configuration or environment variables, you must keep them unique per instance.

Browser/CDP notes (common footgun)

Do not set browser.cdpUrl to the same value on multiple instances.
Each instance requires its own browser control port and CDP range, both derived from its gateway port.
For explicit CDP ports, configure 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, or schtasks services from older installations.
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 verify that reachable probe targets belong to the same gateway. An SSH tunnel, proxy URL, or configured remote URL pointing to the same gateway counts as one gateway with multiple transports, even when the transport ports differ.