[FRD] Cross-gateway federation protocol for OpenClaw

Status: Draft (ByteDesk-internal). Ready to file at openclaw/openclaw issues. Not yet filed. Author: ByteDesk Platform team (companion to ADR-0086 in bytedesk-platform). Reference: docs/gateway/multiple-gateways.md (isolation-only), docs/gateway/operator-scopes.md (operator-trust only).

Problem

OpenClaw today supports multiple gateways via isolation: each gateway is its own trust + workspace domain. Downstream platforms (ByteDesk among them) want to span gateways for topology reasons — EU run, US run, on-prem run — while keeping a coherent workflow control plane on one side.

Without an upstream-blessed bridge protocol, downstream platforms either:

• reuse /v1/chat/completions as a federation transport (which the docs explicitly warn against — it's an operator-grade surface, not an inter-gateway surface), or
• invent ad-hoc transports that fragment trust models across the ecosystem.

Both outcomes are worse than no federation.

Requested upstream primitives

1. Bridge protocol

A documented wire contract for one OpenClaw gateway (call it A) to request that another (B) spawn a session, run a tool/agent/subagent turn, or accept an approval grant — and stream events back. Concretely:

• Request shape: { remoteRunId?, agentTarget, prompt | toolCall | approvalGrant, idempotencyKey, callerIdentity }.
• Response shape: a stream of { event, payload } frames. Event vocabulary at minimum: started, tokenUsage, toolCall, toolResult, phaseEnd, terminal, error.
• Transport: not prescribed in the FRD — HTTP+SSE or gRPC are both reasonable; the doc anchor is what matters.
• Delivery: at-least-once with idempotencyKey honored on B.
• Termination: explicit terminal frame on success/failure/cancel. No reliance on connection close.

2. Cross-gateway identity

A documented way for A to verify that an event coming back from B was signed by B's gateway key. Concretely:

• A signed envelope on each frame, or a session-level signature on the bridge handshake.
• A trust-root document on each gateway listing peer gateway public keys / federation roots.
• A failure mode that fails closed when verification fails.

3. Cross-gateway operator scopes

A documented projection of B's operator scope catalog into A's verification path, so an approval signed by an operator on B can be matched against a scope name A's workflow recognizes. The simplest workable shape:

• Each gateway exposes a signed scope-catalog endpoint listing scope names + descriptions.
• A peers' federation config declares "trust gateway B's sre-lead scope as fulfilling our local sre-lead requirement", explicitly.

Out of scope for this FRD

• Cross-gateway pub/sub. Federation of emit: / subscribe: deliveries adds bridge backpressure semantics on top of the trust model; should be a separate FRD.
• Workspace PV sharing. Each gateway keeps its own workspace.
• Load balancing / autoscaling. Federation is for topology spanning, not horizontal scale.

Downstream design we're holding back

ByteDesk has a placeholder design for a federation: block in our workflow DSL (see ADR-0086 §3.1 in bytedesk-platform). It declares a logical gateway id on an invoke: and resolves through a routing config. We are deliberately holding the design until upstream lands the three primitives above, so the wire contract is owned by OpenClaw and not by a downstream platform.

Why not just use /v1/chat/completions

The upstream docs already warn: "This endpoint is a full operator-access surface. … Only expose this endpoint on loopback, tailnet, or private ingress." Using it as a federation transport conflates operator and inter-gateway trust. An attacker who breaches the bridge channel would obtain operator-grade access to the peer gateway. The federation surface must be distinct.

Asked of upstream

• Confirm whether docs/gateway/multiple-gateways.md will continue to be isolation-only, or whether there's an internal plan to extend.
• If extending: scope the three primitives above into discrete sub-issues.
• If not extending: state that explicitly so downstream platforms can stop holding back federation designs.

Companion ByteDesk artifacts

• ADR-0086 — bytedesk-platform deferral decision + placeholder design.
• docs/research/workflow-federation-status.md — research log.