From 9099520ae23e84b9e9e47224d4a14f1d35bce731 Mon Sep 17 00:00:00 2001
From: Yangfan Wu Bot <39647285+wyf027@users.noreply.github.com>
Date: Sat, 1 Aug 2026 12:21:59 +0800
Subject: [PATCH] docs(media): clarify legacy MEDIA line formatting (#96275)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs(media): clarify legacy MEDIA line formatting

* docs(media): fix heading hierarchy

* docs: update docs map for rich output protocol

---------

Co-authored-by: 吴杨帆 <39647285+leno23@users.noreply.github.com>
---
 docs/docs_map.md                       |  1 +
 docs/reference/rich-output-protocol.md | 29 +++++++++++++++++++++++++-
 docs/start/openclaw.md                 |  6 ++++++
 3 files changed, 35 insertions(+), 1 deletion(-)

diff --git a/docs/docs_map.md b/docs/docs_map.md
index ddc4cf504413..894f6c8c48d2 100644
--- a/docs/docs_map.md
+++ b/docs/docs_map.md
@@ -9153,6 +9153,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
 - Route: /reference/rich-output-protocol
 - Headings:
   - H2: Media attachments
+  - H2: Legacy MEDIA: lines
   - H2: `[embed ...]`
   - H2: Stored rendering shape
   - H2: Related
diff --git a/docs/reference/rich-output-protocol.md b/docs/reference/rich-output-protocol.md
index 44f9d6aaa147..7be84e9b04d3 100644
--- a/docs/reference/rich-output-protocol.md
+++ b/docs/reference/rich-output-protocol.md
@@ -31,7 +31,34 @@ Do not emit text commands for attachments from tools, plugins, streaming blocks,
 Legacy final-reply text may still be normalized for compatibility, but this is not a general plugin/tool protocol.
 </Warning>
 
-Plain Markdown image syntax (`![alt](url)`) stays text by default. Channels that want Markdown images treated as media replies opt in at their outbound adapter; Telegram does this so `![alt](url)` becomes a media attachment.
+## Legacy `MEDIA:` lines
+
+Legacy final assistant replies can still attach local media with a plain
+standalone `MEDIA:` line. The parser only recognizes lines whose trimmed text
+starts with `MEDIA:` outside Markdown wrappers and code fences.
+
+Valid legacy final reply:
+
+```text
+Here is the generated image.
+
+MEDIA:/workspace/image.png
+```
+
+These remain ordinary text and do not attach media:
+
+```text
+**MEDIA:/workspace/image.png**
+`MEDIA:/workspace/image.png`
+Here is your image: MEDIA:/workspace/image.png
+```
+
+Prefer structured `mediaUrl` / `mediaUrls` fields for tools, plugins, browser
+output, streaming blocks, and message actions.
+
+Plain Markdown image syntax stays text by default. Channels that intentionally
+map Markdown image replies to media attachments opt in at their outbound
+adapter; Telegram does this so `![alt](url)` can still become a media reply.
 
 When block streaming is enabled, media must ride on structured payload fields. If the same media URL appears in a streamed block and again in the final assistant payload, OpenClaw delivers it once and strips the duplicate from the final payload.
 
diff --git a/docs/start/openclaw.md b/docs/start/openclaw.md
index 5973ff493863..107bdb7bf77d 100644
--- a/docs/start/openclaw.md
+++ b/docs/start/openclaw.md
@@ -212,6 +212,12 @@ Outbound attachments from the agent use structured media fields on the message t
 
 OpenClaw sends structured media alongside the text. Legacy final assistant replies may still be normalized for compatibility, but tool output, browser output, streaming blocks, and message actions do not parse text as attachment commands.
 
+If you must use a legacy final-reply `MEDIA:` line, keep it as standalone plain
+text. Markdown wrappers, code fences, and inline prose such as
+`**MEDIA:/path.png**`, `` `MEDIA:/path.png` ``, or
+`Here is the image: MEDIA:/path.png` stay text and do not attach media. See
+[Rich output protocol](/reference/rich-output-protocol#legacy-media-lines).
+
 Local-path behavior follows the same file-read trust model as the agent:
 
 - If `tools.fs.workspaceOnly` is `true`, outbound local media paths stay restricted to the OpenClaw temp root, the media cache, agent workspace paths, and sandbox-generated files.