多个 Gateway（同一主机）

大多数情况下用一个 Gateway 就够了，因为单个 Gateway 可以处理多个消息连接和 Agent。如果你需要更强的隔离或冗余（比如备用机器人），可以运行多个独立的 Gateway，每个都有自己的 Profile 和端口。

隔离检查清单（必需）

  • OPENCLAW_CONFIG_PATH — 每个实例独立的配置文件
  • OPENCLAW_STATE_DIR — 每个实例独立的 Session、凭证、缓存
  • agents.defaults.workspace — 每个实例独立的 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

备用机器人指南

在同一台主机上运行第二个 Gateway，它有自己的：

  • Profile/配置
  • 状态目录
  • Workspace
  • 基础端口（加上派生端口）

这样可以让备用机器人与主机器人隔离，当主机器人出问题时，备用机器人可以调试或修改配置。

端口间隔：基础端口之间至少留 20 个端口的间隔，这样派生的浏览器/canvas/CDP 端口就不会冲突。

如何安装（备用机器人）

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

# 备用机器人（隔离的 Profile + 端口）
openclaw --profile rescue onboard
# 注意：
# - Workspace 名称默认会加上 -rescue 后缀
# - 端口至少要比 18789 大 20，
#   最好选择完全不同的基础端口，比如 19789
# - 其余的引导流程和正常情况一样

# 安装服务（如果引导过程中没有自动安装）
openclaw --profile rescue gateway install

端口映射（派生）

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

  • 浏览器控制服务端口 = 基础端口 + 2（仅本地回环）
  • canvasHost.port = 基础端口 + 4
  • 浏览器 Profile 的 CDP 端口从 browser.controlPort + 9 .. + 108 自动分配

如果你在配置或环境变量中覆盖了这些端口，必须确保每个实例都是唯一的。

浏览器/CDP 注意事项（常见陷阱）

  • 不要在多个实例上把 browser.cdpUrl 设置成相同的值。
  • 每个实例需要自己的浏览器控制端口和 CDP 范围（从 Gateway 端口派生）。
  • 如果需要明确指定 CDP 端口，为每个实例设置 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