screen.snapshot: no clean way to send screenshot to messaging channel from agent

[JeffSteinbok]

When an agent calls screen.snapshot, the result is raw base64 in the payload — no clean path to attach it to a Discord/Telegram message without spawning a subagent to decode + write + send it.

An undocumented outPath param exists and saves to the gateway filesystem, but the message tool rejects local paths for image sends anyway.

Preferred fix: return a gateway media ID (like file_fetch does) instead of raw base64 — the message tool already knows how to attach media IDs directly. That would make "take screenshot → send to chat" a one-liner.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 3, 2026, 1:49 AM ET / 05:49 UTC.

Summary
Keep open: current main still returns screenshots as base64/data URLs and has no visible media-ID handoff for chat attachments in this repository, so the requested one-line screenshot-to-channel workflow is not implemented.

Reproducibility: yes. from source inspection: current main returns base64 and a data URL from screen.snapshot, while chat attachments are modeled as base64 content objects rather than a media ID handoff. I did not execute a live gateway/channel flow because this is a read-only review.

Next step
Maintainers should first decide whether media IDs are the stable node-to-chat contract and how to preserve existing base64 consumers.

Review details

Best possible solution:

Define one canonical media handoff contract between node capability results and chat.send, then update screen.snapshot with compatibility for existing base64 consumers and focused regression tests.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection: current main returns base64 and a data URL from screen.snapshot, while chat attachments are modeled as base64 content objects rather than a media ID handoff. I did not execute a live gateway/channel flow because this is a read-only review.

Is this the best way to solve the issue?

Unclear. Returning a media ID may be the right end state, but it crosses the node, gateway, and chat attachment contract and should preserve existing agents that consume base64 or image.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The gateway media-ID contract referenced by the issue is not defined in this checkout, so a Windows-node-only change could drift from the server/chat protocol without maintainer API direction.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 53ff55aff974.

Label changes

Label changes:

• add P3: This is a low-risk ergonomics/API improvement for screenshot-to-chat workflows, not a confirmed regression in an existing documented contract.
• add impact:other: The issue affects an agent workflow for sending screenshots through messaging channels, which is meaningful but outside the specific owned impact classes.
• add issue-rating: 🐚 platinum hermit: Current issue advisory state selects this label.
• add clawsweeper:needs-live-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk ergonomics/API improvement for screenshot-to-chat workflows, not a confirmed regression in an existing documented contract.
• impact:other: The issue affects an agent workflow for sending screenshots through messaging channels, which is meaningful but outside the specific owned impact classes.

Evidence reviewed

What I checked:

• Current screen snapshot response: screen.snapshot builds a data URL and returns format, width, height, base64, and image; there is no media ID field in this response shape. (src/OpenClaw.Shared/Capabilities/ScreenCapability.cs:74, 53ff55aff974)
• Screen capture implementation encodes base64: The platform screen capture path saves the captured bitmap to memory and returns ScreenCaptureResult.Base64, which confirms the current implementation is base64-first. (src/OpenClaw.Tray.WinUI/Services/ScreenCaptureService.cs:119, 53ff55aff974)
• Chat attachment schema is base64 content: ChatAttachment documents the gateway chat.send attachment schema as { type, mimeType, fileName, content } and reads local files into base64 Content, not a media ID reference. (src/OpenClaw.Shared/ChatAttachment.cs:8, 53ff55aff974)
• Chat send forwards attachment objects: OpenClawGatewayClient.SendChatMessageForRunAsync forwards the attachments collection directly to chat.send, so this client-side path currently expects materialized attachment objects. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:331, 53ff55aff974)
• Tests lock in data URL behavior: Capture_ResponseIncludesDataUri asserts that screen.snapshot includes an image property starting with data:image/png;base64,, which matches the reported friction rather than solving it. (tests/OpenClaw.Shared.Tests/CapabilityTests.cs:2210, 53ff55aff974)
• No local media-ID API found: A repository search for file_fetch, mediaId, media_id, and media ID found no matching local implementation surface to reuse for this issue. (53ff55aff974)

Likely related people:

• Régis Brid: Blame and git log --follow point the current screen snapshot response, screen capture plumbing, and chat attachment code to the same recent squashed main commit. (role: recent area contributor; confidence: medium; commits: 7d9152f427a3; files: src/OpenClaw.Shared/Capabilities/ScreenCapability.cs, src/OpenClaw.Tray.WinUI/Services/ScreenCaptureService.cs, src/OpenClaw.Shared/OpenClawGatewayClient.cs)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[jeffsteinbok-openclaw]

Simpler fix than originally described: The gateway already converts a top-level file key in a tool result into a media ID automatically (same pattern used by HA camera tools). So the fix in the companion app is likely just: when screen.snapshot completes, return {"file": "/tmp/screenshot.png"} instead of raw base64. No gateway changes needed — just a one-liner in the companion app's snapshot response handler.

[jeffsteinbok-openclaw]

Quick note on the two screenshot paths available today — they behave quite differently:

nodes invoke screen.snapshot — returns the image as inline base64 in the JSON response body. Works fine for analysis, but the payload is too large to pass directly into another tool call in the same turn (e.g. you can't pipe it straight into message as an attachment).

nodes action="screen_record" — the gateway saves the file to disk and returns FILE:/tmp/shot.png. The message tool accepts this directly via media="file:///tmp/shot.png".

This means screen_record is already a fully usable workaround for sending screenshots to Discord/Telegram without needing a subagent or waiting for the outPath fix — just two tool calls, works every time.

[JeffSteinbok]

Wrote this: https://github.com/JeffSteinbok/openclaw-hub/tree/main/plugins/screenshot-capture to wrap for now.

[JeffSteinbok]

Root cause

This is a gateway-side issue, not a windows-node issue. The node's screen.snapshot correctly returns the capture data.

The gateway already handles this pattern for screen.record — it's listed in SCREEN_DANGEROUS_COMMANDS (blocked from direct invoke) and agents are redirected to the screen_record action, which saves the recording to disk and returns a file path/URL. screen.snapshot is missing the equivalent action wrapper, so its ~1.3M token base64 blob flows through the invoke response inline, bloating context and making it impossible to attach to messaging channels.

Fix

Filed as openclaw/openclaw#90126 — add a first-class screen_snapshot action with parity to screen_record.

Workaround

The screenshot-capture plugin in openclaw-hub does exactly this today as a stopgap.