openclaw - ✅(Solved) Fix docs: MEDIA: directive silently ignored when wrapped in markdown formatting [1 pull requests, 2 comments, 2 participants]

openclaw2026-05-06 13:40:56

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#78495•Fetched 2026-05-07 03:36:16

View on GitHub

Comments

Participants

Timeline

Reactions

Author

mgossman71

Participants

clawsweeper[bot]

mgossman71

Timeline (top)

commented ×2cross-referenced ×1

Error Message

Debugging Difficulty: No error message - complete silent failure

3. Error Feedback

Root Cause

Root Cause: OpenClaw's channel layer parses assistant messages for MEDIA: directives, but the parser doesn't recognize the directive when it's wrapped in markdown formatting.

Fix Action

Fixed

Fixed by PR: docs: clarify MEDIA directive formatting (https://github.com/openclaw/openclaw/pull/78534)

PR fix notes

PR #78534: docs: clarify MEDIA directive formatting

Repository: openclaw/openclaw
Author: Jefsky
State: open | merged: False
Link: https://github.com/openclaw/openclaw/pull/78534

Description (problem / solution / changelog)

Summary

Clarify that MEDIA:<path-or-url> must be an unformatted line-start directive outside code fences.
Add invalid Markdown-wrapped examples to the OpenClaw start docs.
Update assistant output guidance so agents avoid bold, inline-code, and inline-prose MEDIA directives.

Fixes #78495.

Real behavior proof

Behavior or issue addressed: After this patch, the OpenClaw start docs and assistant system prompt explicitly tell users/agents that MEDIA: must be a plain line-start directive outside code fences and without Markdown wrappers.
Real environment tested: Local OpenClaw checkout at /Users/jefskywong/openclaw-work on macOS, branch docs-media-directive-formatting, with repository dependencies installed via pnpm install --frozen-lockfile.
Exact steps or command run after this patch: Ran this Node command against the real changed files in the local checkout:

node - <<'NODE'
const fs = require('node:fs');
const docs = fs.readFileSync('docs/start/openclaw.md', 'utf8');
const prompt = fs.readFileSync('src/agents/system-prompt.ts', 'utf8');
const snippets = [
  docs.match(/The directive must start the line as plain text[^\n]+/)?.[0],
  docs.match(/These forms are not attachment directives[^\n]+/)?.[0],
  prompt.match(/The MEDIA directive must start the line as plain text[^\n]+/)?.[0],
].filter(Boolean);
console.log('OpenClaw local checkout:', process.cwd());
console.log('Docs MEDIA formatting guidance present:', docs.includes('without Markdown wrappers such as bold or inline code'));
console.log('Invalid MEDIA examples present:', docs.includes('**MEDIA:https://example.com/screenshot.png**') && docs.includes('Here is the screenshot: MEDIA:https://example.com/screenshot.png'));
console.log('System prompt MEDIA guidance present:', prompt.includes('Do not write `**MEDIA:...**`'));
console.log('After-fix snippets:');
for (const line of snippets) console.log('- ' + line);
NODE

Evidence after fix: Terminal output from the local OpenClaw checkout:

OpenClaw local checkout: /Users/jefskywong/openclaw-work
Docs MEDIA formatting guidance present: true
Invalid MEDIA examples present: true
System prompt MEDIA guidance present: true
After-fix snippets:
- The directive must start the line as plain text, outside code fences and without Markdown wrappers such as bold or inline code. Example:
- These forms are not attachment directives and will be sent as normal text:
- The MEDIA directive must start the line as plain text, outside code fences and without Markdown wrappers. Do not write `**MEDIA:...**`, `` `MEDIA:...` ``, or inline prose like `Here is the file: MEDIA:...`.",

Observed result after fix: The real changed documentation and prompt source now both contain the after-fix MEDIA formatting guidance and invalid examples, so the shipped docs/prompt copy no longer only states the positive MEDIA: form.
What was not tested: I did not change or test runtime parser behavior; this PR intentionally keeps parser behavior unchanged and only updates docs/prompt copy.

Test plan

git diff --check
pnpm docs:list
pnpm exec oxfmt --check --threads=1 src/agents/system-prompt.ts

Changed files

docs/start/openclaw.md (modified, +9/-1)
src/agents/system-prompt.ts (modified, +1/-0)

Code Example

**MEDIA:/root/.openclaw/workspace/image.png**     ← Wrapped in bold
`MEDIA:/root/.openclaw/workspace/image.png`       ← In code block
Here is your image: MEDIA:...                     ← Inline with text

---

MEDIA:/root/.openclaw/workspace/image.png         ← Plain text, standalone line

---

Warning: MEDIA: directive found inside markdown formatting. Use plain text: MEDIA:/path/to/file.png

RAW_BUFFERClick to expand / collapse

Issue Summary

Problem: The MEDIA: directive for image attachments is silently ignored when wrapped in markdown formatting (bold, code blocks, etc.), causing images to not be delivered to Telegram/Signal/web even though generation succeeds.

Root Cause: OpenClaw's channel layer parses assistant messages for MEDIA: directives, but the parser doesn't recognize the directive when it's wrapped in markdown formatting.

Reproduction

❌ Fails Silently (No Image Delivered)

**MEDIA:/root/.openclaw/workspace/image.png**     ← Wrapped in bold
`MEDIA:/root/.openclaw/workspace/image.png`       ← In code block
Here is your image: MEDIA:...                     ← Inline with text

✅ Works Correctly

MEDIA:/root/.openclaw/workspace/image.png         ← Plain text, standalone line

Impact

Channels Affected: Telegram, Signal, web UI, and any channel using media attachments
User Experience: Images appear to generate successfully but never arrive, causing confusion
Debugging Difficulty: No error message - complete silent failure
Common Mistake: Assistants naturally want to highlight the MEDIA: line with bold formatting

Affected Workflows

This impacts any agent/server that:

Generates images via InvokeAI, Stable Diffusion, or other local tools
Uses OpenAI's image_generate tool
Attaches local image files to messages
Follows examples that show MEDIA: in code blocks (ironically)

Suggested Fixes

1. Documentation Updates

Add explicit warning in docs.openclaw.ai about MEDIA: formatting requirements
Show ✅/❌ examples in media attachment documentation
Note that markdown wrapping breaks the parser

2. Parser Improvement (Optional)

Consider making the MEDIA: parser more robust to recognize the directive even when wrapped in common markdown formatting:

Strip ** before parsing
Strip backticks before parsing
Add warning log when MEDIA: is detected inside markdown

3. Error Feedback

If MEDIA: is detected but delivery fails due to formatting, log a warning like:

Warning: MEDIA: directive found inside markdown formatting. Use plain text: MEDIA:/path/to/file.png

Verification Steps

Users experiencing this issue should:

Check that sharp is installed: npm ls --prefix /usr/lib/node_modules/openclaw sharp
Verify MEDIA: line is plain text (no **bold**, no code)
Check gateway logs for delivery errors: grep -i "sendphoto\|senddocument\|Failed to optimize" /tmp/openclaw/*.log

Environment

OpenClaw Version: v2026.5.5 (and likely earlier versions)
Channels: Telegram (confirmed), likely affects Signal/web UI
Node.js: v22.22.2
OS: Linux 6.8.0-111-generic

This was discovered during InvokeAI integration troubleshooting where images were successfully generated but not delivered to Telegram. The fix required:

Installing missing sharp package
Removing markdown formatting from MEDIA: lines

Priority: Medium-High (silent failure affects user trust in image generation features) Labels: documentation, bug, channels, media

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#conversation history #tool integration #LLM response #prompt template #agent execution

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

openclaw - ✅(Solved) Fix docs: MEDIA: directive silently ignored when wrapped in markdown formatting [1 pull requests, 2 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

3. Error Feedback

Root Cause

Fix Action

Fixed

PR fix notes

PR #78534: docs: clarify MEDIA directive formatting

Description (problem / solution / changelog)

Summary

Real behavior proof

Test plan

Changed files

Code Example

Issue Summary

Reproduction

❌ Fails Silently (No Image Delivered)

✅ Works Correctly

Impact

Affected Workflows

Suggested Fixes

1. Documentation Updates

2. Parser Improvement (Optional)

3. Error Feedback

Verification Steps

Environment

Related

Still need to ship something?

RELATED_DISCOVERY

TRENDING