openclaw - 💡(How to fix) Fix BUG(macOS/Feishu): media://inbound URI resolves to workspace-relative path, image tool fails

Summary

When receiving images via the Feishu (飞书) channel on macOS, the media://inbound/<id>.png URI passed to the image tool fails to resolve to the actual media file path. Instead, it gets treated as a workspace-relative path, resulting in:

[tools] image failed: Local media file not found: /Users/yezz/.openclaw/workspace/media:/inbound/d2ce13c9-ccaf-4f56-ba4e-aabf467523eb.png

Note the :// in media://inbound/... gets collapsed to :/ by path.resolve().

This appears related to #74123 but manifests on macOS with the Feishu channel plugin.

Environment

• OS: macOS (Darwin 25.5.0 arm64)
• OpenClaw: v2026.5.22
• Node: v24.15.0
• Channel: Feishu (飞书)

Steps to Reproduce

1. Send an image via Feishu DM to the bot
2. The image is correctly downloaded to ~/.openclaw/media/inbound/<uuid>.png (confirmed from logs)
3. The message includes [media attached: media://inbound/<uuid>.png]
4. Ask the model to analyze the image (triggers image tool)
5. The image tool fails with Local media file not found

Log Evidence

feishu: post message contains 2 embedded image(s)
feishu: downloaded embedded image img_v3_02121_8ee83670-45ae-4972-9f69-13a2ad55baag, saved to /Users/yezz/.openclaw/media/inbound/d2ce13c9-ccaf-4f56-ba4e-aabf467523eb.png
feishu: downloaded embedded image img_v3_02121_210a2ae2-308c-4e57-94a7-65af5219317g, saved to /Users/yezz/.openclaw/media/inbound/3095c217-ffe0-4a77-9339-97f456944523.png

[tools] image failed: Local media file not found: /Users/yezz/.openclaw/workspace/media:/inbound/d2ce13c9-ccaf-4f56-ba4e-aabf467523eb.png

Root Cause Analysis

The image tool calls loadWebMedia("media://inbound/<id>.png", ...). Inside loadWebMediaInternal:

1. resolveMediaStoreUriToPath() is called to resolve media://inbound/... → returns null (should return physical path)
2. The raw media://inbound/... falls through to path.resolve(workspaceDir, mediaUrl) at line 289
3. On macOS, path.resolve() collapses :// to :/ → workspace/media:/inbound/...
4. File doesn't exist at this path → LocalMediaAccessError

Manual testing confirms resolveInboundMediaReference() and resolveMediaBufferPath() work correctly when called directly — the failure only occurs at gateway runtime.

Workaround

Using the absolute filesystem path directly works:

# Fails: media://inbound/d2ce13c9-ccaf-4f56-ba4e-aabf467523eb.png
# Works: /Users/yezz/.openclaw/media/inbound/d2ce13c9-ccaf-4f56-ba4e-aabf467523eb.png