feat: cross-gateway sessions_send and sessions_spawn via gateway.peers#494
Open
BingqingLyu wants to merge 2 commits into
Open
feat: cross-gateway sessions_send and sessions_spawn via gateway.peers#494BingqingLyu wants to merge 2 commits into
BingqingLyu wants to merge 2 commits into
Conversation
added 2 commits
March 11, 2026 23:58
Add cross-gateway messaging support so agents on different machines
(each running their own OpenClaw gateway) can communicate natively
without SSH script workarounds.
Changes:
1. gateway.peers config map (name -> {url, token})
- Zod schema, TypeScript type, schema label + help
- Peer tokens support SecretInput (env refs, secret stores)
2. sessions_send: gateway/gatewayUrl/gatewayToken params
- Named peer: gateway="imac" resolves from config
- Explicit: gatewayUrl + gatewayToken for ad-hoc targets
- Cross-gateway path: resolve label, send message, wait for
reply, fetch history — all via remote callGateway()
- Local path unchanged (zero breaking changes)
3. sessions_spawn: same gateway/gatewayUrl/gatewayToken params
- Forwards spawn as agent message to remote gateway
- Returns {status, runId, remote: true}
4. gateway-peer.ts: shared peer resolution helper
- Resolves named peers from config with token resolution
- Falls back to explicit gatewayUrl
- Clear error messages with available peer names
5. Tests: 9 new tests for peer resolution (all passing)
- Named peer with/without token
- Missing peer, no peers configured
- Explicit URL override, precedence rules
- Existing 17 sessions tests + 32 config tests still pass
Config example:
gateway:
peers:
imac:
url: wss://imac.local:18789
token: ${env:IMAC_GATEWAY_TOKEN}
studio:
url: wss://studio.local:18789
token: ${env:STUDIO_GATEWAY_TOKEN}
Usage:
sessions_send(sessionKey="agent:jarvis:main", message="hello", gateway="imac")
sessions_spawn(task="run tests", agentId="pepper", gateway="studio")
Closes openclaw#43605
1. Bypass resolveGatewayOptions for peer URLs — it only allows loopback/remote URLs, rejecting valid peer addresses like wss://imac.local:18789. Both sessions-send-tool and sessions-spawn-tool now pass peer URL/token directly to callGateway. 2. Throw on token resolution failure in gateway-peer.ts — previously silently swallowed, which would cause auth failures on the remote gateway with no indication of misconfiguration. 3. Reject unsupported spawn parameters for cross-gateway spawns — runtime, model, thinking, cwd, timeouts, mode, cleanup, sandbox, streamTo, thread, attachments, resumeSessionId are local-only and were silently dropped. Now returns explicit error listing which params are unsupported. 4. Add ws:///wss:// URL format validation on gateway.peers URL in zod-schema via .refine() check. Addresses greptile review on PR openclaw#43656.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
sessions_sendandsessions_spawnonly 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.peersconfig map (new)Named peer gateways so agents can target remote gateways by name instead of raw URLs:
Peer tokens support SecretInput (env refs, secret stores, plaintext).
2.
sessions_send:gateway/gatewayUrl/gatewayTokenparamsWhen cross-gateway params are present:
agentmethodremote: trueflag3.
sessions_spawn: same paramsForwards spawn as an agent message to the remote gateway.
Shared helper:
gateway-peer.tsResolves cross-gateway targeting from tool params:
gateway: "peerName"→ looks upgateway.peers[peerName]gatewayUrl+ optionalgatewayToken→ explicit URL overridePeer names take precedence when both
gatewayandgatewayUrlare provided.Design notes
message,cron,gateway,nodes,canvastools already acceptgatewayUrl/gatewayToken; this extends the pattern to session toolsresolveGatewayOptions()which enforces URL format and token resolution rulesChanges
config/zod-schema.tsgateway.peersrecord schemaconfig/types.gateway.tsGatewayPeerConfigtypeconfig/schema.labels.tsgateway.peersconfig/schema.help.tsgateway.peersagents/tools/gateway-peer.tsagents/tools/sessions-send-tool.tsagents/tools/sessions-spawn-tool.tsagents/tools/gateway-peer.test.tsTests
Closes openclaw#43605