openclaw/docs/gateway/multiple-gateways.md

summary, read_when, title

summary	read_when	title
Run multiple OpenClaw Gateways on one host (isolation, ports, and profiles)	Running more than one Gateway on the same machine You need isolated config/state/ports per Gateway	Multiple Gateways

Multiple Gateways (same host)

Most setups should use one Gateway because a single Gateway can handle multiple messaging connections and agents. If you need stronger isolation or redundancy (e.g., a rescue bot), run separate Gateways with isolated profiles/ports.

Isolation checklist (required)

• 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 ports (browser/canvas) must not overlap

If these are shared, you will hit config races and port conflicts.

Recommended: use the default profile for main, a named profile for rescue

Profiles auto-scope OPENCLAW_STATE_DIR + OPENCLAW_CONFIG_PATH and suffix service names. For most rescue-bot setups, keep the main bot on the default profile and give only the rescue bot a named profile such as rescue.

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

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

Services:

openclaw gateway install
openclaw --profile rescue gateway install

If you want both Gateways to use named profiles, that also works, but it is not required.

Rescue-bot guide

Recommended setup:

• keep the main bot on the default profile
• run the rescue bot on --profile rescue
• use a completely separate Telegram bot for the rescue account
• keep the rescue bot on a different base port such as 19001

This keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down. Leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide.

Recommended rescue channel/account

For most setups, use a completely separate Telegram bot for the rescue profile.

Why Telegram:

• easy to keep operator-only
• separate bot token and identity
• independent from the main bot's channel/app install
• simple DM-based recovery path when the main bot is broken

The important part is full independence: separate bot account, separate credentials, separate OpenClaw profile, separate workspace, and separate port.

Recommended install flow

Use this as the default setup unless you have a strong reason to do something else:

# Main bot (default profile, port 18789)
openclaw onboard
openclaw gateway install

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

During openclaw --profile rescue onboard:

• use the separate Telegram bot token
• keep the rescue profile
• use a base port at least 20 higher than the main bot
• accept the default rescue workspace unless you already manage one yourself

If onboarding already installed the rescue service for you, the final gateway install is not needed.

What onboarding changes

openclaw --profile rescue onboard uses the normal onboarding flow, but it writes everything into a separate profile.

In practice, that means the rescue bot gets its own:

• config file
• state directory
• workspace (by default ~/.openclaw/workspace-rescue)
• managed service name

The prompts are otherwise the same as normal onboarding.

Port mapping (derived)

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

• 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 .. + 108

If you override any of these in config or env, you must keep them unique per instance.

Browser/CDP notes (common footgun)

• Do not pin browser.cdpUrl to the same values on multiple instances.
• Each instance needs its own browser control port and CDP range (derived from its gateway port).
• If you need explicit CDP ports, set browser.profiles.<name>.cdpPort per instance.
• 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 19001

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

Interpretation:

• gateway status --deep helps catch stale launchd/systemd/schtasks services from older installs.
• gateway probe warning text such as multiple reachable gateways detected is expected only when you intentionally run more than one isolated gateway.