多 Gateway（同一主机）

大多数场景应使用一个 Gateway——单个 Gateway 能够处理多个消息连接和 Agent。只有在需要更强隔离或冗余时（例如救援 Bot）才运行独立 Gateway，并配以隔离的 profile 和端口。

就像养龙虾需要隔开的缸，多个 Gateway 实例必须完全隔离，不能共享任何资源。

隔离清单（必须满足）

• OPENCLAW_CONFIG_PATH — 每个实例独立的配置文件
• OPENCLAW_STATE_DIR — 每个实例独立的会话、凭据和缓存
• agents.defaults.workspace — 每个实例独立的工作区根目录
• gateway.port（或 --port）— 每个实例唯一的端口
• 派生端口（浏览器/canvas）不得重叠

若共享上述资源，将出现配置竞争和端口冲突。

推荐方式：使用 profile（--profile）

Profile 自动限定 OPENCLAW_STATE_DIR + OPENCLAW_CONFIG_PATH，并为服务名称添加后缀。

# 主实例
openclaw --profile main setup
openclaw --profile main gateway --port 18789

# 救援实例
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001

按 profile 安装服务：

openclaw --profile main gateway install
openclaw --profile rescue gateway install

救援 Bot 指南

在同一主机上运行第二个 Gateway，拥有独立的：

• profile/config
• state 目录
• 工作区
• 基础端口（加上派生端口）

这使救援 Bot 与主 Bot 完全隔离，在主 Bot 宕机时可用于调试或应用配置变更。

端口间距：基础端口之间至少留 20 个端口，确保派生的浏览器/canvas/CDP 端口不冲突。

安装步骤（救援 Bot）

# 主 Bot（现有或全新，不带 --profile 参数）
# 运行在端口 18789 + Chrome CDC/Canvas/... 端口
openclaw onboard
openclaw gateway install

# 救援 Bot（隔离 profile + 端口）
openclaw --profile rescue onboard
# 注意：
# - workspace 名称默认带 -rescue 后缀
# - 端口应至少为 18789 + 20，
#   建议选完全不同的基础端口，如 19789
# - 其余 onboarding 步骤与普通流程相同

# 安装服务（若 setup 期间未自动完成）
openclaw --profile rescue gateway install

端口映射（派生）

基础端口 = gateway.port（或 OPENCLAW_GATEWAY_PORT / --port）。

• 浏览器控制服务端口 = 基础端口 + 2（仅 loopback）
• Canvas 主机由 Gateway HTTP 服务器提供（与 gateway.port 同端口）
• 浏览器 Profile 的 CDP 端口从 browser.controlPort + 9 .. + 108 自动分配

若在配置或环境变量中覆盖任意派生端口，必须确保每个实例唯一。

浏览器/CDP 常见坑点

• 不要将 browser.cdpUrl 固定为多个实例相同的值。
• 每个实例需要独立的浏览器控制端口和 CDP 范围（从其 Gateway 端口派生）。
• 若需显式指定 CDP 端口，在每个实例中按 profile 设置 browser.profiles.<name>.cdpPort。
• 远程 Chrome：使用 browser.profiles.<name>.cdpUrl（按 profile、按实例）。

手动环境变量示例

OPENCLAW_CONFIG_PATH=~/.openclaw/main.json \
OPENCLAW_STATE_DIR=~/.openclaw-main \
openclaw gateway --port 18789

OPENCLAW_CONFIG_PATH=~/.openclaw/rescue.json \
OPENCLAW_STATE_DIR=~/.openclaw-rescue \
openclaw gateway --port 19001

快速检查

openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status