telegram-ui: document reliable local-media delivery and recovery

[EdgeClaws]

Summary

Could telegram-ui own a short, reliable local-media delivery path for screenshots and generated files?

Today, one useful warning lives only in a host-specific Mermaid note: generic /tmp media may be rejected, so stage the file in the workspace before sending. That lesson applies to every Telegram image/file workflow, not just Mermaid diagrams, and agents handling device/browser screenshots will not naturally read the Mermaid skill.

This is a documentation/skill request, not a request to weaken OpenClaw's local-file trust boundary.

Observed failure

On OpenClaw 2026.9.1, a simple Telegram screenshot handoff failed twice:

1. Raw image data was passed through a local-path-style input and was interpreted as a nonexistent filename.
2. The PNG was staged under generic /tmp, which the active media roots rejected with Local media path is not under an allowed directory.
3. Staging the same file under the active agent workspace and sending it with the CLI document fallback succeeded and returned a message ID.

The underlying runtime model is reasonable: outbound local media follows the agent's effective file-read trust, tools.fs.workspaceOnly, and agent/group/sender read policy. The issue is that the skill does not currently turn that into a compact operational path.

Why this belongs in telegram-ui

The rule is source-agnostic. The image may come from Maestro, browser control, Mermaid, image generation, a PDF renderer, or another tool. The Telegram skill owns the final handoff and delivery confirmation, while source skills should only explain how to produce the artifact.

Requested guidance

Please add a concise local-media subsection or extend the existing Media rule to cover:

1. media / path / filePath inputs are path-or-URL references, not raw image bytes. If a public buffer input is supported, document its exact encoding, filename/content-type, and size contract separately.
2. Prefer an existing agent-readable workspace or OpenClaw-managed media path for generated files. Phrase generic /tmp as potentially rejected by the active media roots, not globally forbidden.
3. Do not recommend loosening filesystem policy just to send one file. If a readable host path is rejected, stage the artifact in the workspace and retry.
4. Count delivery as confirmed only when the response is positive (ok: true) and includes a message ID.
5. Use the first-class message media send first. After an explicit error or user-confirmed non-delivery, retry promptly from the workspace path with the documented openclaw message send ... --force-document --json fallback.
6. Preserve the existing distinction between inline photos and forceDocument, and between short media captions and separate rich-body text.

Suggested compact copy

Local media inputs take a path or URL, not raw image bytes. For generated files, prefer an agent-readable workspace path; generic /tmp may fall outside the active media roots. Confirm delivery from ok: true plus a message ID. After an explicit error or user-confirmed non-delivery, stage the file in the workspace and retry once with the CLI --force-document --json fallback.

Acceptance examples

It would help to include two small recipes in the existing payload reference:

• normal inline screenshot send from an absolute workspace path;
• document fallback using the same file, with replyTo and a JSON receipt.

That would keep SKILL.md lean while making the full recovery path copyable.