Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Feature]: Cross-gateway messaging (sessions_send between machines) [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#43605•Fetched 2026-04-08 00:16:54
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
SPFAdvisorsSPFAdvisors
Participants
SPFAdvisorsSPFAdvisors
Timeline (top)
cross-referenced ×3referenced ×1

sessions_send only works within the same gateway. In multi-machine setups (e.g., agents split across a MacBook, iMac, and Mac Studio each running their own gateway), there's no native way for agents on different gateways to communicate.

Root Cause

sessions_send only works within the same gateway. In multi-machine setups (e.g., agents split across a MacBook, iMac, and Mac Studio each running their own gateway), there's no native way for agents on different gateways to communicate.

Fix Action

Fix / Workaround

Current Workaround

SSH scripts with base64 encoding (msg-jarvis, msg-pepper) that shell into the remote machine and run openclaw agent. Works but fragile — requires SSH key setup, correct PATH exports, and doesn't integrate with session history.

PR fix notes

PR #43656: feat: cross-gateway sessions_send and sessions_spawn via gateway.peers

Description (problem / solution / changelog)

Problem

sessions_send and sessions_spawn only work within a single gateway. In multi-machine setups (agents split across MacBook, iMac, Mac Studio — each running their own OpenClaw gateway), there's no native way for agents to communicate cross-gateway. The current workaround is SSH scripts (msg-jarvis), which are fragile and bypass all gateway auth/routing.

Solution

Add cross-gateway routing to session tools via three complementary mechanisms:

1. gateway.peers config map (new)

Named peer gateways so agents can target remote gateways by name instead of raw URLs:

gateway:
  peers:
    imac:
      url: wss://imac.local:18789
      token: \${env:IMAC_GATEWAY_TOKEN}
    studio:
      url: wss://studio.local:18789

Peer tokens support SecretInput (env refs, secret stores, plaintext).

2. sessions_send: gateway / gatewayUrl / gatewayToken params

sessions_send(sessionKey="agent:jarvis:main", message="hello", gateway="imac")
sessions_send(sessionKey="agent:pepper:main", message="hi", gatewayUrl="wss://custom:18789", gatewayToken="tok")

When cross-gateway params are present:

  • Label resolution happens on the remote gateway
  • Message is sent via remote agent method
  • Wait + history fetch all route to remote
  • Response includes remote: true flag
  • Local session resolution, visibility checks, and A2A flow are bypassed (the remote gateway owns those)

3. sessions_spawn: same params

sessions_spawn(task="run tests", agentId="pepper", gateway="studio")

Forwards spawn as an agent message to the remote gateway.

Shared helper: gateway-peer.ts

Resolves cross-gateway targeting from tool params:

  1. gateway: "peerName" → looks up gateway.peers[peerName]
  2. gatewayUrl + optional gatewayToken → explicit URL override
  3. Neither → local gateway (returns undefined, no behavior change)

Peer names take precedence when both gateway and gatewayUrl are provided.

Design notes

  • Zero breaking changes — local path is completely unchanged
  • Pattern already exists — message, cron, gateway, nodes, canvas tools already accept gatewayUrl/gatewayToken; this extends the pattern to session tools
  • Security — peer URLs are validated through existing resolveGatewayOptions() which enforces URL format and token resolution rules

Changes

FileChange
config/zod-schema.tsgateway.peers record schema
config/types.gateway.tsGatewayPeerConfig type
config/schema.labels.tsLabel for gateway.peers
config/schema.help.tsHelp text for gateway.peers
agents/tools/gateway-peer.tsNew — shared peer resolution helper
agents/tools/sessions-send-tool.tsCross-gateway fast path + 3 new schema params
agents/tools/sessions-spawn-tool.tsCross-gateway fast path + 3 new schema params
agents/tools/gateway-peer.test.tsNew — 9 tests for peer resolution

Tests

  • 9 new peer resolution tests (named peer, missing peer, explicit URL, precedence, error messages)
  • 17 existing sessions tests pass
  • 32 existing config schema tests pass

Closes #43605

Changed files

  • src/agents/tools/gateway-peer.test.ts (added, +97/-0)
  • src/agents/tools/gateway-peer.ts (added, +72/-0)
  • src/agents/tools/sessions-send-tool.ts (modified, +190/-0)
  • src/agents/tools/sessions-spawn-tool.ts (modified, +103/-0)
  • src/config/schema.help.ts (modified, +2/-0)
  • src/config/schema.labels.ts (modified, +1/-0)
  • src/config/types.gateway.ts (modified, +13/-0)
  • src/config/zod-schema.ts (modified, +16/-0)
RAW_BUFFERClick to expand / collapse

Description

sessions_send only works within the same gateway. In multi-machine setups (e.g., agents split across a MacBook, iMac, and Mac Studio each running their own gateway), there's no native way for agents on different gateways to communicate.

Environment

  • OpenClaw 2026.3.8
  • 3 machines: MacBook (1 agent), iMac (7 agents), Mac Studio (1 agent)
  • Each running its own gateway instance
  • Connected via Tailscale

Current State

  • sessions_send validates agent IDs against local config and fails if the target agent isn't on the same gateway
  • openclaw agent with OPENCLAW_GATEWAY_URL pointing to a remote gateway also doesn't work — CLI validates agent IDs locally first
  • The only working cross-gateway communication method is SSH + openclaw agent --agent <id> --message '<text>' on the remote machine

Proposed Solutions

  1. Gateway federation — gateways discover each other (via Tailscale, mDNS, or manual config) and can route sessions_send to remote agents
  2. Remote agent registry — config option to register agents on remote gateways: remoteAgents: [{id: "jarvis", gateway: "ws://100.82.32.94:18789"}]
  3. Message relay — a lightweight relay that accepts messages and forwards them to the correct gateway based on agent ID

Current Workaround

SSH scripts with base64 encoding (msg-jarvis, msg-pepper) that shell into the remote machine and run openclaw agent. Works but fragile — requires SSH key setup, correct PATH exports, and doesn't integrate with session history.

Impact

Essential for anyone running a distributed agent setup. As OpenClaw grows, multi-machine deployments will become more common (home server + laptop, office + cloud, etc.).

extent analysis

Fix Plan

To enable cross-gateway communication, we will implement a Remote Agent Registry. This involves adding a configuration option to register agents on remote gateways.

Steps

  • Add a remoteAgents configuration option to the gateway config file:
remoteAgents:
  - id: "jarvis"
    gateway: "ws://100.82.32.94:18789"
  - id: "pepper"
    gateway: "ws://100.82.32.95:18789"
  • Update the sessions_send function to check the remote agent registry before validating agent IDs locally:
def sessions_send(agent_id, message):
    # Check remote agent registry
    for remote_agent in config.remoteAgents:
        if remote_agent.id == agent_id:
            # Send message to remote gateway
            send_message_to_gateway(remote_agent.gateway, agent_id, message)
            return
    # If not found in remote registry, validate locally
    validate_agent_id_locally(agent_id)
    send_message_locally(agent_id, message)
  • Implement the send_message_to_gateway function to forward messages to the correct gateway:
import websocket

def send_message_to_gateway(gateway_url, agent_id, message):
    ws = websocket.create_connection(gateway_url)
    ws.send(json.dumps({"agent_id": agent_id, "message": message}))
    ws.close()

Verification

To verify that the fix worked, test sending messages between agents on different gateways using the sessions_send function.

Extra Tips

  • Ensure that the remoteAgents configuration option is properly formatted and updated on all gateways.
  • Consider implementing authentication and authorization for remote agent registry to prevent unauthorized access.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#permission error#memory optimization#batch processing#GPU compatibility#agent setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [Feature]: Cross-gateway messaging (sessions_send between machines) [1 pull requests, 1 participants]