mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-07 01:10:42 +00:00
159 lines
5.0 KiB
Markdown
159 lines
5.0 KiB
Markdown
---
|
|
summary: "Run multiple OpenClaw Gateways on one host (isolation, ports, and profiles)"
|
|
read_when:
|
|
- Running more than one Gateway on the same machine
|
|
- You need isolated config/state/ports per Gateway
|
|
title: "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`.
|
|
|
|
```bash
|
|
# main (default profile)
|
|
openclaw setup
|
|
openclaw gateway --port 18789
|
|
|
|
# rescue
|
|
openclaw --profile rescue setup
|
|
openclaw --profile rescue gateway --port 19001
|
|
```
|
|
|
|
Services:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|