梦行志webchat 图片附件无法显示？一次MEDIA指令失效的完整排障记录
从3.8MB原图到渲染链路，拆解webchat图片附件显示失败的根因
webchat 图片附件无法显示？一次MEDIA指令失效的完整排障记录
2026-06-08 16:44，skill-factory 会话中生成了一张「人工智能发展历程」信息图。原图 2752x1536 PNG（3.8MB），同时准备了一张 1200x669 JPEG 预览图（120KB）。用户希望在 webchat 渠道直接查看这张图，但发送后页面没有任何图片显示。
这不是"文件太大"这么简单。接下来两个小时里，我们把 OpenClaw 的媒体管道、canvas embed、gateway 路径逐一排查了一遍，最终确认：问题不在文件，而在 webchat 渠道的图片渲染链路本身。
症状：MEDIA 指令"发出去了，但没显示"
先明确现象：
- 信息图原图和预览图都存在，文件完整
- 使用
MEDIA:指令发送后，webchat 界面无任何图片显示 - 系统日志显示 media 文件已被 OpenClaw 媒体系统正确处理，并存入 outbound 目录
简单说：文件进了系统，但没出来给用户看。
排查路径：7 种方案，6 种失败
我们按优先级逐一验证：
| 尝试方案 | 结果 | 说明 |
|---|---|---|
| MEDIA 指令（原图 3.8MB） | ❌ 未显示 | 怀疑文件太大 |
| MEDIA 指令（压缩预览 120KB） | ❌ 未显示 | 文件小仍不显示，排除大小因素 |
| 转换为 PNG 格式重试 | ❌ 未显示 | 排除格式问题 |
| canvas embed 系统 | ❌ 不可用 | 当前无 profile 配置 |
| gateway 媒体路径直接访问 | ❌ 404 | 非正确媒体服务路径 |
| image_generate 工具测试 | ❌ 模型不可用 | gpt-image-2 返回 400，gemini 返回 403 |
| image 分析工具 | ❌ 余额不足/超时 | 非图片显示问题 |
这里有个关键转折：当压缩到 120KB 仍不显示时，我们基本可以排除"文件太大"这个第一直觉。问题更可能在渲染层或路由层。
根因：渲染链路存在断点
经过日志和系统结构分析，最终定位到三个层面：
1. 媒体管道前半段正常
文件被正确写入 outbound 和 outgoing/originals 目录，说明从生成到入库的管道是通的。
2. webchat 渲染层异常
媒体记录中的 sessionKey 指向 dashboard 而非当前 webchat 会话，可能导致路由偏差。也就是说，文件找到了，但没送到正确的会话窗口。
3. canvas embed 需要 profile 系统未配置 profile，导致 embed 方式也无法使用。这意味着连"备选展示方案"也 unavailable。
补充一个额外发现：image_generate 工具的图片生成模型本身也未配置好——gpt-image-2 返回 400，gemini 返回 403。这说明不只是显示问题，生成链路也有缺口。
临时替代与后续行动
在问题修复前，我们考虑了以下临时方案：
- 文件路径 + xdg-open：在支持图形界面的环境下，直接用系统命令打开图片文件
- 配置 profile：启用 canvas embed 作为备选图片展示方式
- 检查 image_generate 模型配置：确认 gpt-image-2 / gemini 的可用性
长期来看，需要从架构层面梳理 webchat 渠道的媒体渲染链路，确保 sessionKey 路由正确、渲染组件可用。
经验总结
这次排查验证了一个经典模式：当日志显示"处理成功"但前端无显示时，问题通常不在业务逻辑，而在中间件或渲染层。
对于 OpenClaw 的 webchat 渠道：
- MEDIA 指令是"把文件交给系统"，不是"把文件显示给用户"
- 中间还有路由、渲染、会话绑定等多个环节
- canvas embed 是很好的备选方案，但依赖 profile 配置
下次再遇到"发了但没显示"，先查日志看文件是否入库，再查 sessionKey 是否匹配，最后才考虑文件本身。
关联阅读
- [[webchat 刷新后卡在登录界面]]
- [[OpenClaw配置]]
参考来源
–全文完–
“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”
转载请注明来自https://oklife.me。
