PR #67723: fix(agents): allow workspaceOnly inbound image loads from managed media dir

• Repository: openclaw/openclaw
• Author: lucasheriques
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/67723

Description (problem / solution / changelog)

Note: AI-assisted (Claude Opus 4.6). Lightly tested: unit tests added (34/34 pass), pnpm build + pnpm check clean, live-verified via bundle patch against 2026.4.14 on my install. Pre-review with codex review --base upstream/main — iteration below reflects its feedback.

Summary

• Problem: Multimodal agents with tools.fs.workspaceOnly: true cannot see inbound images on channels like WhatsApp/Telegram/Discord. The native image loader rejects paths like ~/.openclaw/media/inbound/<uuid>.jpg with Path escapes sandbox root, even though OpenClaw's own inbound pipeline wrote them. Agents then hallucinate content from the [media attached: ...] text reference.
• Fix: skip assertSandboxPath when the target is inside path.join(getMediaDir(), "inbound"). Mirrors the existing media://inbound/<id> URI path in the same file, which already treats the inbound media dir as trusted.
• What did NOT change: The lexical resolveSandboxPath check is untouched. workspaceOnly still blocks reads from arbitrary paths, from other media/ subdirs (outbound, tool-*, remote-cache), from other agents' workspaces, from credentials dirs, etc. Sandboxed agents (with a sandbox runtime) follow resolveSandboxedBridgeMediaPath, unchanged.

Change Type (select all)

• Bug fix

Scope (select all touched areas)

• Skills / tool execution
• Integrations

Linked Issue/PR

• Closes #59278 (exact match — same error message, same code path)
• Related #64434 (same root cause; NemoClaw shipped a broader symlink workaround downstream waiting for this fix)
• Related #54445 (same pattern on the outbound onBlockReply path, not addressed here)
• This PR fixes a bug or regression

Root Cause

The workspaceOnly && !sandbox branch of loadImageFromRef always enforces assertSandboxPath, whose lexical path.relative check fails for any path outside the workspace root — including OpenClaw-managed inbound media paths. The sibling media://inbound/<id> URI branch already treats the same directory as trusted; the raw-path branch was missing the equivalent check.

Regression Test Plan

Three new unit tests in src/agents/pi-embedded-runner/run/images.test.ts:

• Positive: workspaceOnly: true + no sandbox + path inside getMediaDir()/inbound/ → image loads
• Negative (Codex-feedback-driven): same config + path inside media/outbound/ or media/tool-image-generation/ → still rejected
• Negative: same config + path outside both workspace and media dir → still rejected

All pass. Full images.test.ts (34 tests) passes. pnpm build + pnpm check clean.

User-visible / Behavior Changes

Multimodal agents with workspaceOnly: true can now actually see inbound images on channel-driven turns. Default-config agents unaffected. Sandboxed agents unaffected.

Security Impact (required)

• New permissions/capabilities? No — narrow exception for the inbound-attachment subdir OpenClaw itself writes on message receipt
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? Yes, narrowly. workspaceOnly agents can now read from ~/.openclaw/media/inbound/. Other media/ subdirs (outbound, tool-*, remote-cache) and everything else remain blocked by the unchanged assertSandboxPath. Negative-control tests lock both in.

Known tradeoff (flagged by codex review, left for maintainer judgment)

codex review noted that this broadens the effective read surface beyond the existing opaque media://inbound/<id> exemption. Specifically: an absolute inbound path referenced in a past turn's transcript could be re-read in a future turn. The strictly tighter fix would be a per-turn allowlist of paths the gateway injected into the current inbound context, checked instead of a directory prefix.

I didn't implement that here because:

1. It's a larger surgery — needs plumbing through detectAndLoadPromptImages / loadImageFromRef options
2. This PR already moves workspaceOnly agents from hallucinating → seeing correct content, which is the user-facing fix
3. The narrower directory-prefix bypass is still strictly safer than the current broken alternatives being shipped downstream (e.g., NemoClaw's symlink of the entire stateDir/media into the workspace per #64434)

Happy to either (a) land this as a pragmatic step and track the per-turn allowlist as a follow-up, or (b) expand this PR if maintainers prefer. Will defer to your call.

Repro

WhatsApp agent with tools.fs.workspaceOnly: true + openai-codex/gpt-5.4. Send image in DM. Before: promptImages=0, hallucinated reply, debug log shows Native image: failed to load ...: Path escapes sandbox root (~/.openclaw/workspace-<name>): .... After: verified locally by patching the installed bundle with the same logic; agent describes actual image contents correctly.

Changed files

• src/agents/pi-embedded-runner/run/images.test.ts (modified, +92/-0)
• src/agents/pi-embedded-runner/run/images.ts (modified, +16/-6)