fix(message): pass agentId through gateway RPC for media root resolution by Sid-Qin · Pull Request #23249 · openclaw/openclaw

Sid-Qin · 2026-02-22T04:29:24Z

Summary

Problem: The `message` tool's gateway RPC drops `agentId` from the request, causing media file sends for non-default agents to fail with path resolution errors.
Why it matters: Users with multi-agent setups cannot send media files from non-default agent workspaces.
What changed: Added `agentId` to `SendParamsSchema`, forwarded it from `src/infra/outbound/message.ts` to the gateway, and used it as the preferred agent ID in `src/gateway/server-methods/send.ts`. Regenerated protocol files (`protocol.schema.json`, Swift `GatewayModels.swift`).
What did NOT change: Default agent behavior is unchanged. If no `agentId` is provided, the existing `resolveSessionAgentId` logic applies.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes [Bug]: message tool gateway RPC drops agentId, breaking media sends for non-default agents #23043

User-visible / Behavior Changes

Media sends from non-default agents now resolve file paths against the correct agent workspace
No config changes required

Security Impact (required)

New permissions/capabilities? `No`
Secrets/tokens handling changed? `No`
New/changed network calls? `No` (same RPC, added field)
Command/tool execution surface changed? `No`
Data access scope changed? `No` — agentId only affects which agent workspace is used for media root resolution, within existing permission boundaries

Repro + Verification

Environment

OS: macOS 15.3 (arm64)
Runtime: Node v22+
Integration/channel: Any channel with media support

Steps

Configure multiple agents with different workspaces
Send a media file using the `message` tool from a non-default agent
Verify the file path resolves against the correct agent workspace

Expected

Media file is sent successfully from the non-default agent's workspace

Actual

Before fix: `agentId` was dropped, media root resolved against default agent
After fix: `agentId` propagates through RPC, correct workspace is used

Evidence

`SendParamsSchema` updated with `agentId: Type.Optional(Type.String())`
Protocol files regenerated via `pnpm protocol:gen && pnpm protocol:gen:swift`
CI `protocol:check` passes after including generated files

Human Verification (required)

Verified scenarios: Traced agentId flow from `message.ts` → `callMessageGateway` → `send.ts` → `derivedAgentId`; confirmed explicit agentId takes priority over session-derived ID
Edge cases checked: Missing/empty agentId falls back to `resolveSessionAgentId`; whitespace-only agentId is trimmed and ignored
What I did not verify: Live multi-agent media send (no multi-agent setup available)

Compatibility / Migration

Backward compatible? `Yes` — agentId is `Type.Optional`, existing callers without it work unchanged
Config/env changes? `No`
Migration needed? `No`

Failure Recovery (if this breaks)

How to disable/revert this change quickly: Revert the three source files and regenerated protocol files
Files/config to restore: `src/infra/outbound/message.ts`, `src/gateway/server-methods/send.ts`, `src/gateway/protocol/schema/agent.ts`, generated protocol files
Known bad symptoms: If agentId is passed incorrectly, media root could resolve to wrong workspace

Risks and Mitigations

Risk: An invalid agentId string could cause unexpected workspace resolution
- Mitigation: The explicit agentId is only used when non-empty after trim; otherwise falls back to existing logic

Closes openclaw#23043 The direct delivery path in sendMessage() correctly passes params.agentId to deliverOutboundPayloads, but the gateway path omitted it from the callMessageGateway RPC params. The gateway handler then fell back to the default agent's workspace for media root resolution, causing LocalMediaAccessError for non-default agents. - Add agentId to the SendParams schema - Forward params.agentId in the gateway RPC call - Prefer the explicit agentId over the derived default in the handler Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

@Sid-Qin

Landed from #23249 by @Sid-Qin. Includes extra regression tests for agentId precedence + blank fallback. Co-authored-by: Sid <201593046+Sid-Qin@users.noreply.github.com>

steipete · 2026-02-25T23:31:56Z

Landed on main in commit 2011edc9e (rebased from temp commit 89b0bf199).

What we shipped from this PR:

Added agentId to gateway SendParams schema.
Forwarded agentId in the gateway send RPC path.
Updated gateway send handling to prefer agentId explicitly provided by caller, then session-derived, then default.
Added/expanded regression tests for:
- gateway RPC forwarding of agentId
- explicit-agent precedence
- blank-agent fallback behavior
Regenerated Swift gateway protocol models.
Added changelog entry with attribution to fix(message): pass agentId through gateway RPC for media root resolution #23249.

Validation run before landing:

pnpm lint
pnpm build
pnpm test

Thanks for the focused patch and root-cause writeup, @Sid-Qin.

@Sid-Qin