openclaw - 💡(How to fix) Fix WebChat image uploads disappear from Control UI history and media:// refs fail in image tool [2 pull requests]

Bug

WebChat image uploads can disappear from the Control UI after the optimistic message is replaced by chat.history. The model may still eventually answer, but the persisted user message no longer renders the uploaded image, and the image tool can initially fail to load the uploaded media://inbound/... ref.

Repro

1. Start OpenClaw with a text-first/session model where WebChat image uploads are routed through media paths.
2. Open the Control UI chat.
3. Send a message with an image attachment, for example: What is in this image?
4. Watch the message immediately after send, then after the run/history refresh completes.

Actual

The uploaded image appears briefly as an optimistic local preview, then disappears after history reload.

The persisted transcript user message contains fallback text like:

What is in this image?
[media attached: media://inbound/image---....png]

but does not contain structured MediaPath / MediaPaths, so the Control UI has no stable history-backed image to render.

In the same run, the image tool may first try to load:

media://inbound/image---....png

and resolve it incorrectly under the workspace, producing a path like:

.../.openclaw/workspace/media:/inbound/image---....png

The model may recover by searching for the physical file, but that is slow and unreliable.

Expected

WebChat image uploads should remain visible after chat.history reloads.

The persisted user transcript row should carry renderable media metadata, for example MediaPath / MediaPaths and media types, not only a fallback [media attached: media://...] text marker.

The image tool should resolve media://inbound/... through the managed inbound media store before applying workspace-relative path handling.

Notes from investigation

This is visible on current stable/release and still present after rebasing onto current origin/main.

Relevant paths:

• src/gateway/server-methods/chat.ts
  • rewriteChatSendUserTurnMediaPaths still finds the persisted user turn by exact text match against parsedMessage.
  • Real persisted content can include timestamp and media marker text, so the rewrite can miss and never add MediaPath / MediaPaths.
• src/agents/tools/image-tool.ts
  • media:// refs are classified as allowed, but when workspaceDir exists they can still fall through the relative-path branch and become an invalid workspace path.

Regression context:

• e6d04550ca (fix(gateway): route WebChat images through imageModel) routed WebChat image uploads through configured image model inline handling.
• 55a0c9b1f4 (fix(gateway): restore WebChat image understanding routing) removed that override path and routes text-only WebChat image uploads through media paths again.
• That exposed the fragile transcript rewrite and image-tool media ref resolution gaps.

Impact

• Control UI loses uploaded image previews after history refresh.
• Existing chat history cannot reliably render user-uploaded images when transcript metadata is missing.
• Image understanding can be delayed or fail because the image tool initially receives a media://inbound/... ref but resolves it incorrectly.