OpenClaw Multiple Gateways: Keep Control Planes Isolated

Most OpenClaw operators should run one Gateway. That is the default for a reason: one Gateway can own the agent, sessions, auth profiles, browser profiles, channels, and node connections without making you think about port maps before coffee.

But sometimes one Gateway is not enough. You may want a rescue bot that can help when the primary setup is down. You may want a clean test control plane that does not touch production sessions. You may want two agents on the same host without their browser control ports, config writes, or workspaces bleeding into each other.

The OpenClaw multiple-gateway docs are blunt about the tradeoff. Separate Gateways are for stronger isolation or redundancy. If you do this, isolation is not a vibe. It is a checklist: config path, state directory, workspace root, base port, derived ports, and browser/CDP profile settings all need to stay separate.

One Gateway owns one control plane

The remote access docs define the Gateway host as where the agent lives. That host owns sessions, auth profiles, channels, and state. Nodes connect to the Gateway over the Gateway WebSocket and return tool results, but nodes do not run the Gateway service.

That model matters when you add a second Gateway. You are not adding a second UI window. You are adding another control plane. It can have its own config, state, credentials, caches, workspace, browser control service, and channel connections. If those surfaces overlap accidentally, you have not built redundancy. You have built a race condition with a nicer name.

I would only run multiple Gateways when the isolation goal is concrete. A rescue Gateway is concrete. A production and staging split is concrete. Two different teams sharing a host but requiring different workspaces is concrete. "I clicked setup twice and now both respond" is not a plan.

The isolation checklist is the product

The required OpenClaw checklist has five items. Each Gateway instance needs its own OPENCLAW_CONFIG_PATH, its own OPENCLAW_STATE_DIR, its own agents.defaults.workspace, a unique gateway.port or --port, and non-overlapping derived ports for browser and canvas surfaces.

That first pair is easy to underestimate. OPENCLAW_CONFIG_PATH points an instance at its config file. OPENCLAW_STATE_DIR points it at sessions, credentials, and caches. If two instances share either one, you can get config races, credential confusion, or a clean-looking test run that quietly used production state.

The workspace matters just as much. The config docs show agents.defaults.workspace as the default workspace root. If a rescue bot and a production bot write into the same workspace, you lose the audit boundary that made the rescue bot useful. Give each instance a workspace that tells you, by path alone, which control plane touched it.

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace-rescue"
    }
  }
}

The useful habit is to name every persistent surface after the role of the Gateway: main, rescue, staging, or whatever your operational language is. When a future incident happens, you should not have to decode which process owns ~/.openclaw-2.

Use profiles unless you need manual env wiring

The recommended path is profiles. The multiple-gateway docs say --profile auto-scopes OPENCLAW_STATE_DIR and OPENCLAW_CONFIG_PATH, and it suffixes service names. That is exactly the kind of boring automation you want when the mistake class is "two processes shared a control file."

# main control plane
openclaw --profile main setup
openclaw --profile main gateway --port 18789

# rescue control plane
openclaw --profile rescue setup
openclaw --profile rescue gateway --port 19001

Profiles do not remove the need to think about ports. In the example above, the main Gateway uses 18789 and the rescue Gateway uses 19001. The docs recommend leaving at least 20 ports between base ports so derived browser, canvas, and CDP ports do not collide.

If you install them as services, keep the profile on the service install command too:

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

Manual environment variables are still supported, and they are useful when you are writing a launch script or debugging an instance outside the normal profile flow:

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

Manual wiring gives you control, but it also gives you more ways to be subtly wrong. If you use it, write the config path, state directory, workspace, and port in one place. Do not split them across shell history, a launch agent, and a half-edited JSON file.

Ports have children

The base port is gateway.port, or the value supplied through OPENCLAW_GATEWAY_PORT or --port. The multiple-gateway docs also document derived ports. The browser control service uses base plus 2, the canvas host is served on the Gateway HTTP server at the same base port, and browser profile CDP ports auto-allocate from browser.controlPort + 9 through browser.controlPort + 108.

This is why a port conflict can show up somewhere that does not look like the Gateway. Your base WebSocket might bind cleanly while a browser control service or CDP range collides with another instance. If you override any derived value in config or environment, you own the uniqueness problem.

The docs call out one common footgun directly: do not pin browser.cdpUrl to the same values on multiple instances. Each instance needs its own browser control port and CDP range. If you need explicit CDP ports, configure browser.profiles.<name>.cdpPort per instance. If a browser is remote, use browser.profiles.<name>.cdpUrl per profile and per instance.

That is not cosmetic. Browser automation is often the most privileged thing an agent does. If your rescue Gateway accidentally attaches to the production browser profile, it can inherit logged-in sessions, open tabs, and operator context that were never meant to cross the boundary.

Remote mode does not change ownership

The remote docs describe SSH tunnels and tailnets as ways for clients to reach a Gateway. They do not make a second machine own the agent. The Gateway still owns sessions, auth profiles, channels, and state.

A loopback tunnel to a non-default Gateway looks like this:

ssh -N -L 19001:127.0.0.1:19001 user@host

With the tunnel up, a local client can target ws://127.0.0.1:19001. You can persist that target in config using remote mode:

{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://127.0.0.1:19001",
      token: "your-token"
    }
  }
}

The docs include an important credential rule for remote calls. When you pass --url, the CLI does not fall back to config or environment credentials. You must include --token or --password explicitly. That is a good safety feature. It prevents a script from silently reusing credentials for a target it did not mean to trust.

Also remember the remote security default: keep the Gateway loopback-only unless you deliberately need a bind. For trusted private networks, insecure private WebSocket access is a break-glass client setting, not the normal public-exposure plan. Non-loopback binds must use auth tokens or passwords.

A rescue Gateway should not share the accident

The rescue-bot pattern is the clearest use case for multiple Gateways. The docs describe running a second Gateway on the same host with its own profile, config, state directory, workspace, base port, and derived ports. That keeps the rescue bot isolated from the main bot so it can debug or apply config changes if the primary bot is down.

Notice what the rescue bot is not. It is not a second process watching the same config file. It is not a backup channel bolted onto the same credential store. It is not a browser profile pointed at the same CDP port. It is another control plane that can survive the primary control plane's mistake because it did not share the mistaken surface.

The install flow in the docs keeps the main bot normal and puts the rescue bot behind an isolated profile. During onboarding, the rescue workspace name is postfixed with -rescue by default. The port should be at least 20 ports away from the main base port; the docs suggest choosing a clearly different base port such as 19789.

Use checks before you operate

After you start multiple Gateways, prove that each one answers as the intended instance:

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

These are deliberately boring checks. status tells you whether the profiled Gateway is reachable. browser status tells you whether the browser surface for that profile is healthy. Run them before you restart anything, pair a node, open a browser task, or assume a broken channel belongs to the main bot.

I also like to write down a tiny control-plane card for every instance: profile name, config path, state dir, workspace, base port, browser control port, expected browser profile names, and whether it is allowed to touch production channels. If that feels like too much paperwork, that is a sign you probably want one Gateway, not two.

When I would not run multiple Gateways

I would not use multiple Gateways to separate ordinary conversations. OpenClaw already has session and channel configuration for normal isolation needs. I would not use multiple Gateways because a port was busy once. Fix the process that should not be running, then keep the architecture simple.

I would not use multiple Gateways to avoid understanding config validation either. The configuration docs say OpenClaw validates config strictly. Unknown keys, malformed types, and invalid values make the Gateway refuse to start, leaving diagnostic commands such as openclaw doctor, openclaw logs, openclaw health, and openclaw status available. That failure mode is useful. Do not route around it with a second mystery process.

The operator rule is simple: run one Gateway until you can say exactly what the second Gateway isolates. Then isolate every persistent and network surface, not just the process name.

Multiple Gateways are a production tool, not a decoration. Used carefully, they let you keep a rescue path, a staging control plane, or a genuinely separate agent boundary on the same host. Used casually, they create the worst kind of agent bug: two systems that both look alive while neither one owns the truth cleanly.

Want the complete guide? Get ClawKit — $9.99