openclaw - 💡(How to fix) Fix Design input needed: cross-gateway messaging primitive for distributed OpenClaw deployments [1 comments, 2 participants]

Summary

There is no native primitive in OpenClaw today for sending a message from an agent on one gateway to an agent on a different gateway. sessions_send and related session-routing tools are gateway-local. Bridging two OpenClaw deployments today requires operator-built ad-hoc transport (HTTP between gateway RPC endpoints, custom tool plugins, generic external channels) — there is no canonical pattern.

Filing this to surface the architectural gap and invite community design input. We are explicitly not proposing a fix. There are real trade-offs (auth, transport, protocol, blast radius) and the right shape isn't obvious.

Why this matters

Multi-OC topologies show up naturally:

• Multi-machine / VM — different OC instances per host, agents on each want to coordinate across.
• Multi-tenant separation — per-team or per-user OC instances for isolation, but with cross-team workflows.
• Sidecar specialist OC — one OC carries a heavy or specialized plugin (e.g. deep-observability tooling, a different model provider) and the main OC wants to delegate "investigate this" / "diagnose this" / "hand-off this user" messages to it, then receive results back.
• Shared backend, separate front-ends — see #72016 for the exact scenario where one VM runs two gateways for family-member separation; cross-coordination would extend the same pattern to messaging.

Each of these requires the operator to invent their own bridge today. Each invention is independent, bespoke, and security-sensitive.

What works today

• Native sessions_send only within a single gateway.
• Operator-built bridges:
  • HTTP bridge — agent on OC-A uses exec + curl to call OC-B's gateway RPC. Works, but every agent has to know the protocol and credentials.
  • Custom plugin tool — wraps the HTTP call as a registered OpenClaw tool. Cleaner per-agent surface, but bespoke and per-deployment.
  • Shared external channel — both OCs subscribe to the same chat platform or pub/sub bus. Works, but adds an external dependency, may be slow or lossy, and the message contract is the external channel's, not OpenClaw's.

None of these are wrong. None of them are standard.

The trade-off that makes this hard

A native cross-gateway primitive would standardize identity, auth, retries, and the message envelope — but it would also:

• Open a new attack surface (one OC reachable from another → blast-radius implications under compromise).
• Force a transport choice (direct ws? https? p2p? broker?).
• Possibly conflict with what looks today like a "one gateway, one trust boundary" mental model.

So this isn't a "just add it" issue. It's a "how should this look, if it's added at all" issue.

Open questions for the community

1. Is there demand for this from real deployments? We hit it the moment we ran two OC instances side-by-side. Would be curious whether others do.
2. What's the right transport? Direct gateway-to-gateway, or always through a broker / shared service? Push-based or pull-based?
3. What's the auth / identity model? Mutual API keys, mTLS, OIDC, capability tokens? How does the receiving agent know "this message came from OC-A's agent X" with confidence?
4. What's the addressing scheme? Resolve gateway-host/agent-id directly, or via a registry / discovery service?
5. Does this belong in core OpenClaw, or in a plugin? Plugin keeps core small but loses standardization. Core surface guarantees a contract but expands surface area.
6. Is there a published pattern from other multi-agent / agent-to-agent frameworks (A2A protocol drafts, MCP server-to-server, distributed swarm patterns, etc.) worth borrowing?

What this issue is not

• Not a feature request — no specific implementation is being asked for.
• Not a bug — single-gateway operation is correct and intentional today.
• Not a tooling request — workarounds exist; we're asking about the canonical primitive.

Repro / use case

Two OpenClaw instances on the same host: one main, one in a separate sandboxed stack with a different plugin set. Want an agent on Main to delegate an investigation to a specialist agent on the sandbox-side OC, then receive the result back as a usable response. Doable today with HTTP + curl glue, but no standard pattern exists. The same shape generalizes to multi-machine deployments.