PR #70719: fix(gateway): persist webchat images as managed media

• Repository: openclaw/openclaw
• Author: steipete
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/70719

Description (problem / solution / changelog)

Summary

• Problem: Control UI chat history could lose generated/assistant images because history sanitization strips raw image bytes and the UI had no durable media reference to load after reload.
• Why it matters: image-only replies and generated images appeared live, then disappeared from the web UI chat after history reload.
• What changed: assistant image replies are copied into managed Gateway media storage, persisted in transcript content as authenticated media URLs, served through a scoped /api/chat/media/outgoing/.../full route, and rendered by the Control UI through authenticated blob fetches.
• What did NOT change (scope boundary): provider/model input plumbing still uses existing image attachment paths; sensitive media is still not persisted into transcript content.

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

• Closes #70674
• Related #70507
• Related #55671
• Related #58543
• Related #70383
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: image replies were stored/displayed as raw inline data or legacy media strings, while chat.history intentionally strips large inline image payloads for safety.
• Missing detection / guardrail: no regression covered an assistant image reply across chat.send -> transcript persistence -> chat.history -> Control UI render.
• Contributing context: the previous UI-side image history work handled existing renderable references, but did not create durable references for assistant/generated image payloads.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file:
  • src/gateway/server.chat.gateway-server-chat.test.ts
  • src/gateway/managed-image-attachments.test.ts
  • ui/src/ui/chat/grouped-render.test.ts
• Scenario the test should lock in: assistant image data URL replies become managed media blocks in chat.history, raw base64 is absent from history payloads, and the UI fetches managed image URLs with auth/session headers before rendering.
• Why this is the smallest reliable guardrail: it exercises the gateway persistence boundary, the authenticated media route, and the exact UI render path without requiring a live provider.
• Existing test that already covers this (if any): none.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Control UI chat reloads can display assistant/generated images through durable managed media URLs instead of depending on inline base64 history payloads.

Diagram (if applicable)

Before:
assistant image reply -> inline data / MEDIA text -> chat.history strips bytes -> no image

After:
assistant image reply -> managed media record -> transcript URL -> authenticated UI fetch -> image renders

Security Impact (required)

• New permissions/capabilities? Yes
• Secrets/tokens handling changed? No
• New/changed network calls? Yes
• Command/tool execution surface changed? No
• Data access scope changed? Yes
• If any Yes, explain risk + mitigation: the new media route serves only managed image records. It requires gateway HTTP auth, chat.history scope, requester session ownership for non-privileged auth, UUID attachment ids, and verifies the attachment is still referenced by the transcript before serving bytes.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Node/pnpm repo checkout
• Model/provider: mocked gateway chat dispatcher
• Integration/channel (if any): Control UI / webchat
• Relevant config (redacted): default local test config; QA mock-openai lane

Steps

1. Send a webchat assistant reply payload with mediaUrls: [data:image/png;base64,...].
2. Wait for final chat event and reload chat.history.
3. Verify the assistant message content contains /api/chat/media/outgoing/.../full image blocks and no raw base64.
4. Render the history message in Control UI and verify the UI fetches the managed image with auth/session headers and renders a blob preview.

Expected

• History contains a durable image URL and renders an image after reload.

Actual

• Before this fix, history could omit the image bytes and render no image.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • pnpm test src/gateway/managed-image-attachments.test.ts src/gateway/server.chat.gateway-server-chat.test.ts ui/src/ui/chat/grouped-render.test.ts
  • pnpm test src/gateway/server-methods/chat.directive-tags.test.ts src/gateway/managed-image-attachments.test.ts src/gateway/server.chat.gateway-server-chat.test.ts ui/src/ui/chat/grouped-render.test.ts
  • pnpm check:changed
  • pnpm build
  • pnpm openclaw qa suite --provider-mode mock-openai --scenario control-ui-qa-channel-image-roundtrip --output-dir .artifacts/qa-e2e/managed-images-control-ui-pr70719 --concurrency 1
• Edge cases checked:
  • auth/session gating for managed media route
  • invalid/non-image sources skipped without leaking local paths
  • sensitive image media is not persisted into transcript content
  • directive tags remain persisted where needed while broadcast text remains clean
• What you did not verify:
  • live provider image generation against a paid provider; mock QA exercised a real Control UI browser session and qa-channel image history reload.

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
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: managed media records could outlive transcript references.
  • Mitigation: cleanup runs from chat.history, transient records expire, and the media route refuses records no longer referenced by transcript history.
• Risk: browsers cannot attach Authorization headers to raw <img> tags.
  • Mitigation: Control UI fetches managed images with auth/session headers and renders blob URLs.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/web/control-ui.md (modified, +1/-0)
• src/gateway/managed-image-attachments.test.ts (added, +992/-0)
• src/gateway/managed-image-attachments.ts (added, +1097/-0)
• src/gateway/server-http.ts (modified, +23/-0)
• src/gateway/server-methods/chat.directive-tags.test.ts (modified, +3/-4)
• src/gateway/server-methods/chat.ts (modified, +352/-24)
• src/gateway/server.chat.gateway-server-chat.test.ts (modified, +94/-0)
• ui/src/ui/chat/grouped-render.test.ts (modified, +90/-0)
• ui/src/ui/chat/grouped-render.ts (modified, +139/-18)