docs: clarify rescue bot gateway setup (#69788)

* docs: clarify rescue bot gateway setup

* docs: make rescue bot guide more prescriptive
This commit is contained in:
Tak Hoffman
2026-04-21 12:29:40 -05:00
committed by GitHub
parent ddc1d9aa54
commit 09c5669299

View File

@@ -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
```