OpenClaw 多 Gateway 网关部署指南:同一主机上的配置隔离、状态隔离与端口规划
OpenClaw 多 Gateway 网关部署指南:同一主机上的配置隔离、状态隔离与端口规划
单个 Gateway 网关实例足以支撑多消息连接与多个智能体,这是大多数场景下的推荐配置。但当你在同一台主机上需要更强的隔离性(互不干扰的配置、状态与端口)或冗余能力(例如主机器人宕机时仍可调试的"救援机器人")时,就需要以隔离的配置文件、状态目录与端口运行多个 OpenClaw Gateway。本文将基于 OpenClaw 仓库的 --profile 机制与派生端口规则,完整讲解多 Gateway 的部署方法、端口映射原理与常见陷阱,读完后你可以安全地在单机上并行运行多个互不冲突的网关实例。
何时需要多个 Gateway,何时不需要
多 Gateway 不是默认选项。从源码与 CLI 提示看,OpenClaw 明确推荐"一台机器一个 Gateway":
- 单个 Gateway 网关可以同时处理多个消息连接(Telegram、Discord、Slack 等)和多个智能体,绝大多数场景无需拆分;
- cli/daemon-cli/status.print.ts 中针对多网关场景给出了明确建议:"Recommendation: run a single gateway per machine for most setups. One gateway supports multiple agents",同时指出 "If you need multiple gateways (e.g., a rescue bot on the same host), isolate ports + config/state"。
因此,选择多 Gateway 的合理动机只有两类:
- 强隔离:多个实例各自持有独立的配置、会话凭证、缓存与工作区,互不可见、互不影响;
- 冗余/救援:主机器人出问题时,救援机器人仍可独立运行,用于调试主机器人或应用配置更改(详见下文"救援机器人指南")。
隔离检查清单(必需项)
在同一主机上运行多个 Gateway,以下五项必须逐实例隔离,否则会引发配置竞争与端口冲突:
| 隔离项 | 作用 | 设置方式 |
|---|---|---|
OPENCLAW_CONFIG_PATH |
每个实例的配置文件 | 环境变量(或由 --profile 自动限定) |
OPENCLAW_STATE_DIR |
每个实例的会话、凭证、缓存 | 环境变量(或由 --profile 自动限定) |
agents.defaults.workspace |
每个实例的工作区根目录 | 配置文件 |
gateway.port(或 --port) |
每个实例唯一的基础端口 | 配置或 CLI 参数 |
| 派生端口(浏览器/画布) | 由基础端口自动派生,不得重叠 | 自动派生,基础端口间距足够即安全 |
如果这些项被共享,你会遇到典型的配置竞争(两个实例互相覆盖配置/状态)和端口冲突(EADDRINUSE 或浏览器/CDP 端口互抢)。其中 OPENCLAW_GATEWAY_PORT 环境变量与配置文件中的 gateway.port 均可设定基础端口,从 config/paths.test.ts 的测试用例看,环境变量优先级高于配置文件。
推荐方案:--profile 配置文件
OpenClaw 的 --profile <名称> 根选项是多实例部署的首选方式。它会自动完成状态目录、配置路径的隔离,并为服务名称添加后缀,极大降低人工配置环境变量的出错概率。
--profile 的底层实现
从 cli/profile.ts 的源码可以看清其原理:
- 解析:
parseCliProfileArgs()在 CLI 启动时解析--profile(也支持--profile=值形式),值仅允许字母、数字、_、-,规则定义在 cli/profile-utils.ts(/^[a-z0-9][a-z0-9_-]{0,63}$/i),保证路径安全且 shell 友好;--profile与--dev不能同时使用; - 状态目录:
resolveProfileStateDir()将 profile 映射为~/.openclaw-<profile>(profile 为default时无后缀,即默认的~/.openclaw); - 环境注入:
applyCliProfileEnv()在 cli/run-main.ts 启动路径中被调用,会自动设置OPENCLAW_PROFILE,并仅在未显式设置时填充OPENCLAW_STATE_DIR与OPENCLAW_CONFIG_PATH(默认配置文件路径为<状态目录>/openclaw.json),因此显式环境变量永远优先于 profile 默认值; - 特别的
devprofile 会默认使用端口 19001。
基本用法
# main 实例
openclaw --profile main setup
openclaw --profile main gateway --port 18789
# rescue 实例
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001
每个 profile 拥有独立的配置文件与状态目录,--port 指定各自唯一的基础端口。
按 profile 安装为系统服务
两个实例各自注册为独立系统服务(launchd / systemd / schtasks,见 cli/daemon-cli/install.ts):
openclaw --profile main gateway install
openclaw --profile rescue gateway install
服务安装时会读取当前 profile 环境中的端口与配置,并合并已有服务的环境变量。若服务已存在但配置变化,需要显式使用 openclaw gateway install --force 重新安装,CLI 的错误提示中也会引导你从相同的 --profile / OPENCLAW_STATE_DIR 环境重跑该命令。
救援机器人指南
"救援机器人"是在同一主机上运行的第二个 Gateway,使用独立的配置文件、状态目录、工作区、基础端口(加上全部派生端口),与主机器人完全隔离,从而在主机器人宕机时仍可调试或应用配置更改。
端口间距原则:在基础端口之间至少留出 20 个端口的间距,这样派生的浏览器/画布/CDP 端口永远不会冲突(派生规则见下一节)。
安装步骤
# 主机器人(现有或新建,不带 --profile 参数)
# 运行在端口 18789 + Chrome CDP/Canvas/... 派生端口
openclaw onboard
openclaw gateway install
# 救援机器人(隔离的配置文件 + 端口)
openclaw --profile rescue onboard
# 注意:
# - 工作区名称默认会添加 -rescue 后缀
# - 端口应至少为 18789 + 20 个端口,
# 最好选择完全不同的基础端口,如 19789,
# - 其余的新手引导与正常相同
# 安装服务(如果在新手引导期间没有自动完成)
openclaw --profile rescue gateway install
采用 --profile rescue 后,状态目录自动变为 ~/.openclaw-rescue,配置路径变为 ~/.openclaw-rescue/openclaw.json,工作区默认带 -rescue 后缀;如果你需要自定义工作区根目录,可在 rescue 的配置文件中显式设置 agents.defaults.workspace。
派生端口映射:从基础端口自动推导
基础端口 = gateway.port(或 OPENCLAW_GATEWAY_PORT / --port)。其余服务端口全部从基础端口按固定偏移派生,规则在 config/port-defaults.ts 中定义:
| 服务 | 端口公式 | 默认值(基础端口 18789) |
|---|---|---|
| Bridge 端口 | 基础 + 1 | 18790 |
| 浏览器控制服务端口 | 基础 + 2(仅 loopback) | 18791 |
| Canvas Host 端口 | 基础 + 4 | 18793 |
| 浏览器配置文件 CDP 端口范围 | 控制端口 + 9 .. + 108 自动分配 | 18800 – 18899 |
对应源码函数:
deriveDefaultBridgePort(gatewayPort)=gatewayPort + 1;deriveDefaultBrowserControlPort(gatewayPort)=gatewayPort + 2;deriveDefaultCanvasHostPort(gatewayPort)=gatewayPort + 4;deriveDefaultBrowserCdpPortRange(controlPort):起始为controlPort + 9,结束为起始 + 99(默认常量DEFAULT_BROWSER_CDP_PORT_RANGE_START = 18800、END = 18899),跨度 100 个端口,正好对应文档所说的"控制端口 + 9 .. + 108"。
这一派生逻辑在 browser/src/browser/config.ts 的 resolveBrowserConfig() 中实际生效:先从 Gateway 端口解析出控制端口与 CDP 范围,未配置 browser.cdpUrl 时,默认 CDP 端点即为 http://127.0.0.1:<controlPort + 1>。只要基础端口间距足够(≥20),所有派生端口就天然不会重叠——这正是救援机器人指南中要求端口间距的根本原因。
如果你在配置或环境变量中覆盖了这些派生端口(例如显式设置 canvasHost.port 或 browser.cdpPortRangeStart),则必须手动保证每个实例都唯一。canvasHost.port 在 config/zod-schema.ts 中定义为正整数端口,相关配置项 canvasHost.enabled、canvasHost.root、canvasHost.port、canvasHost.liveReload 的说明可在 config/schema.base.generated.ts 中查到;browser.cdpPortRangeStart 的值会被校验在 1..65535 之间且不能超出端口范围窗口(见 browser/src/browser/config.ts 的 resolveCdpPortRangeStart)。
浏览器/CDP 注意事项(常见陷阱)
浏览器相关配置是多实例部署最容易踩坑的地方,务必注意:
- 不要在多个实例上将
browser.cdpUrl固定为相同的值,否则两个实例会尝试连接/复用同一个 CDP 端点; - 每个实例需要自己的浏览器控制端口和 CDP 范围,这些端口从其自身 Gateway 端口派生,因此只要基础端口隔离正确,派生端口自动隔离;
- 如果你需要显式的 CDP 端口,请为每个实例分别设置
browser.profiles.<name>.cdpPort; - 远程 Chrome 场景:使用
browser.profiles.<name>.cdpUrl(按配置文件、按实例分别设置)。
这些配置项的类型定义在 config/types.browser.ts:
browser.profiles.<name>.cdpPort:该 profile 的 CDP 端口,创建时分配一次并持久化;browser.profiles.<name>.cdpUrl:该 profile 的 CDP URL(用于远程 Chrome);browser.cdpUrl:全局 CDP 端点基础 URL(默认是派生端口上的 loopback CDP);browser.cdpPortRangeStart:自动分配 profile 时的本地 CDP 起始端口(默认从 Gateway 端口派生)。
在 browser/src/browser/chrome.ts 的实现中,启动浏览器时会构造 http://127.0.0.1:<cdpPort>、传入 --remote-debugging-port=<cdpPort>,并通过 ensurePortAvailable(profile.cdpPort) 与 isChromeReachable(cdpUrl) 做端口可用性检查与启动探测——这解释了为何端口冲突会在浏览器启动阶段立刻暴露。
手动环境变量方式(不借助 --profile)
如果你不使用 --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
这是 --profile 内部所做工作的手工等价版:--profile 只是"便捷填充默认值,绝不覆盖显式环境变量"(见 cli/profile.ts 中的注释与实现),因此在脚本化、容器化或 CI 场景中,手工设置环境变量反而更直接可控。
快速检查
部署完成后,可用以下命令快速确认各实例状态与浏览器情况:
openclaw --profile main status
openclaw --profile rescue status
openclaw --profile rescue browser status
若出现端口占用或服务状态异常,检查要点依次为:各实例基础端口是否唯一且间距 ≥20、OPENCLAW_CONFIG_PATH / OPENCLAW_STATE_DIR 是否指向各自目录、agents.defaults.workspace 是否各自独立、是否在配置或环境变量中手动覆盖了会重叠的派生端口(浏览器控制端口、canvasHost.port、CDP 范围)。按此排查即可定位绝大多数多实例冲突问题。
小结
多 Gateway 部署的核心只有三句话:能用一个就不用多个;确需多个时,逐实例隔离配置、状态、工作区与基础端口;基础端口间距保持 20 以上,派生端口(Bridge +1、浏览器控制 +2、Canvas +4、CDP +9..+108)就会自动错开。优先使用 --profile,它把状态目录、配置路径和服务名称的隔离一次做完,手动环境变量方式则适合脚本化场景。按本文清单执行,即可在同一主机上安全运行主机器人与救援机器人等多套互不干扰的 Gateway 实例。