openclaw - 💡(How to fix) Fix image tool can't resolve telegram:file/ references for Telegram photos

Summary

When a Telegram user sends a photo, the image tool (used by the LLM to inspect images) can't resolve telegram:file/<file_id> references. The media IS downloaded correctly to disk, but the internal URI scheme never gets resolved to a local path before the tool call.

Reproduction

1. User sends a photo via Telegram DM
2. The photo gets downloaded & saved to media/inbound/<uuid>.jpg ✅
3. The LLM receives the reference as telegram:file/AgACAgQ... in the conversation context
4. When the LLM tries to call the image tool with that reference, it fails — the tool only understands file paths, http(s)://, data:, and file:// URIs

Root cause

In message-cache-BSVhrw8x.js, the mediaRef is set to telegram:file/${fileId}:

...fileId ? { mediaRef: `telegram:file/${fileId}` } : {},

Meanwhile, attachment-normalize-D55neHIL.js downloads and saves the file correctly, producing media://inbound/${savedMedia.id}:

const mediaRef = `media://inbound/${savedMedia.id}`;

But the telegram:file/... reference in the conversation context is never resolved to the corresponding media://inbound/... path (or local filesystem path). The two pipelines don't connect.

Workaround

Manually checking ls -lt media/inbound/ for the most recent file matching the message timestamp works, but is fragile and adds latency.

Suggested fix

Resolve telegram:file/<file_id> → local filesystem path (or media://inbound/<id>) before the message context reaches the LLM. The file has already been downloaded at that point — the reference just needs to be updated.

Environment

• OpenClaw v2026.5.18
• Telegram channel plugin enabled
• Headless Ubuntu 24.04 host