PR #63479: fix(cli): stage local media before gateway send #63461

• Repository: openclaw/openclaw
• Author: jepson-liu
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63479

Description (problem / solution / changelog)

Summary

• Problem: openclaw message send --channel whatsapp --media <path> reported success but only text was delivered (hasMedia: false), because WhatsApp outbound uses deliveryMode: "gateway" and the CLI only sent raw filesystem path strings over the gateway RPC. The gateway only reads local media under agent-scoped roots; arbitrary paths (e.g. under home or /tmp) were not loadable.
• Why it matters: Users expect CLI sends to behave like agent-driven sends, which persist media via saveMediaSource into managed storage first.
• What changed: Before callMessageGateway for send, local paths outside allowed roots are copied with saveMediaSource(..., "outbound") on the CLI host; http(s) and opaque refs (e.g. media:) are unchanged; paths already under getAgentScopedMediaLocalRoots are not duplicated. New helper: src/infra/outbound/message-gateway-media.ts; wired from src/infra/outbound/message.ts. Tests in src/infra/outbound/message-gateway-media.test.ts.
• What did NOT change (scope boundary): Gateway wire protocol, WhatsApp plugin outbound adapter, remote-gateway / cross-machine file transfer (still path-string only over RPC).

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

Fixes #63461 Related #51347

User-visible / Behavior Changes

• CLI message send for channels whose outbound uses gateway delivery (including WhatsApp) now stages out-of-root local --media paths into the managed media directory before invoking the gateway, so attachments can be read and sent when CLI and gateway run on the same host with a normal filesystem.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No (same CLI flags; behavior for valid sends improves)
• Data access scope changed? No (still reads only user-supplied paths; staging uses existing saveMediaSource / size limits)

Repro + Verification

Environment

• OS: Linux (dev); behavior intended same on macOS/Windows for local gateway
• Runtime: Node 22+
• Channel: WhatsApp (gateway delivery mode)

Steps

1. Place a media file outside default media roots (e.g. under home or a non–OpenClaw tmp path).
2. Run: openclaw message send --channel whatsapp --target <jid-or-e164> --media /path/to/file -m "test" (with gateway running locally as usual for your setup).

Expected

• Message delivers with media attachment (not text-only).

Actual (before fix)

• Text delivered; logs showed no effective media / hasMedia: false style behavior for disallowed paths.

Evidence

• Unit tests: pnpm test src/infra/outbound/message-gateway-media.test.ts (and src/infra/outbound/message.test.ts as part of local gate)

Human Verification (required)

• Verified scenarios: Logic review + unit tests for staging vs pass-through vs in-root paths.
• Edge cases checked: HTTPS passthrough; Windows drive paths not misclassified as opaque schemes (code path).
• What I did not verify: End-to-end WhatsApp Web send with real account (requires live gateway + WhatsApp session).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Failure Recovery (if this breaks)

• Revert the commit touching src/infra/outbound/message.ts and remove message-gateway-media.ts / test file.

Risks and Mitigations

• Risk: Extra disk write and brief copy for large files within existing media size limits.
  • Mitigation: Same saveMediaSource path as other tooling; skips copy when already under allowed roots.

Changed files

• src/infra/outbound/message-gateway-media.test.ts (added, +85/-0)
• src/infra/outbound/message-gateway-media.ts (added, +118/-0)
• src/infra/outbound/message.ts (modified, +15/-4)