From 09c5669299aaa2e53bbf866c577ec242a9adff99 Mon Sep 17 00:00:00 2001
From: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
Date: Tue, 21 Apr 2026 12:29:40 -0500
Subject: [PATCH] docs: clarify rescue bot gateway setup (#69788)

* docs: clarify rescue bot gateway setup

* docs: make rescue bot guide more prescriptive
---
 docs/gateway/multiple-gateways.md | 94 ++++++++++++++++++++++---------
 1 file changed, 66 insertions(+), 28 deletions(-)

diff --git a/docs/gateway/multiple-gateways.md b/docs/gateway/multiple-gateways.md
index 3576e6a81e8..840596d2e8d 100644
--- a/docs/gateway/multiple-gateways.md
+++ b/docs/gateway/multiple-gateways.md
@@ -20,60 +20,98 @@ Most setups should use one Gateway because a single Gateway can handle multiple
 
 If these are shared, you will hit config races and port conflicts.
 
-## Recommended: profiles (`--profile`)
+## 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.
+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`.
 
 ```bash
-# main
-openclaw --profile main setup
-openclaw --profile main gateway --port 18789
+# main (default profile)
+openclaw setup
+openclaw gateway --port 18789
 
 # rescue
 openclaw --profile rescue setup
 openclaw --profile rescue gateway --port 19001
 ```
 
-Per-profile services:
+Services:
 
 ```bash
-openclaw --profile main gateway install
+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
 
-Run a second Gateway on the same host with its own:
+Recommended setup:
 
-- profile/config
-- state dir
-- workspace
-- base port (plus derived ports)
+- 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.
+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.
 
-Port spacing: leave at least 20 ports between base ports so the derived browser/canvas/CDP ports never collide.
+### Recommended rescue channel/account
 
-### How to install (rescue bot)
+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:
 
 ```bash
-# Main bot (existing or fresh, without --profile param)
-# Runs on port 18789 + Chrome CDC/Canvas/... Ports
+# Main bot (default profile, port 18789)
 openclaw onboard
 openclaw gateway install
 
-# Rescue bot (isolated profile + ports)
+# Rescue bot (separate Telegram bot, separate profile, port 19001)
 openclaw --profile rescue onboard
-# Notes:
-# - workspace name will be postfixed with -rescue per default
-# - Port should be at least 18789 + 20 Ports,
-#   better choose completely different base port, like 19789,
-# - rest of the onboarding is the same as normal
-
-# To install the service (if not happened automatically during setup)
 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`).
@@ -95,7 +133,7 @@ If you override any of these in config or env, you must keep them unique per ins
 
 ```bash
 OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
-OPENCLAW_STATE_DIR=~/.openclaw-main \
+OPENCLAW_STATE_DIR=~/.openclaw \
 openclaw gateway --port 18789
 
 OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
@@ -106,10 +144,10 @@ openclaw gateway --port 19001
 ## Quick checks
 
 ```bash
-openclaw --profile main gateway status --deep
+openclaw gateway status --deep
 openclaw --profile rescue gateway status --deep
 openclaw --profile rescue gateway probe
-openclaw --profile main status
+openclaw status
 openclaw --profile rescue status
 openclaw --profile rescue browser status
 ```