bug: edit_image ignores Windows terminal paths (C:\…): treated as URL, returns 404

在 Open WebUI 中通过 Windows 终端(如 Open Terminal / Tether 连接的 Windows 设备)把本地图片交给内置 edit_image 工具做编辑时出现。工具只把以 / 开头的路径当成终端文件去读取,Windows 绝对路径 C:\... 不满足这个判断,被

快速结论:在 Open WebUI 中通过 Windows 终端(如 Open Terminal / Tether 连接的 Windows 设备)把本地图片交给内置 edit_image 工具做编辑时出现。工具只把以 / 开头的路径当成终端文件去读取,Windows 绝对路径 C:\... 不满足这个判断,被原样当作 URL 发给图片服务,最终返回 404。优先排查路径判断逻辑与终端上传来源。

适用环境:Open WebUI v0.13.4(Docker 镜像 ghcr.io/open-webui/open-webui:v0.13.4);服务端为 Linux 容器;终端为 Windows 11 上的 Open Terminal 0.17.x,经 Tether 中继作为个人设备接入。报告者确认 dev 分支中相关代码行未改动,但未在 dev 上实际运行验证。Issue 未提供 Python、CUDA、显卡或具体模型信息。

最快修复方案:暂无确认的一步修复方案。Issue 提出并等待验证的修复思路是:在 tools/builtin.py 的两处路径判断中,除 posixpath.isabs() 外同时接受 ntpath.isabs(),并继续排除 /api/v1/files/、含 :// 的 URL 和 data: 开头的数据。可优先尝试,但属于待验证改动,并非官方已合并方案。

注意事项:不要用手动把路径改写为 /api/v1/files/... 或 Linux 路径的方式绕过,否则只是换了一种输入来源,实际含义不同。修改源码后需重新构建或重启容器。Issue 中并未给出修复提交或发布版本,升级前请先核对目标版本是否已包含该改动。

问题场景

用户接入一台运行在 Windows 上的终端(Open Terminal 0.17.x,经 Tether 中继作为个人设备连接),并在聊天中选中该终端,将 Chat Uploads 设为 Filesystem。此时附加的 JPG 会落在 Windows 工作目录,模型收到的是 Windows 绝对路径(如 C:/Users/me/workspace/photo.jpg 或 C:\\Users\\me\\workspace\\photo.jpg)。在开启 Image Generation 与 Image Edit 后,让模型“编辑这张图片”,模型调用内置 edit_image 工具,工具无法读取终端上的源图片,编辑失败并返回 404。同一张图以 /api/v1/files/... URL 形式传入,或从 Linux/macOS 终端传入时,编辑可以正常完成。

报错原文

bug: edit_image ignores Windows terminal paths (C:\...): treated as URL, returns 404

{"error": "404: We could not find what you're looking for :/"}

原因分析

最可能的原因是路径分类逻辑只支持 POSIX 绝对路径。backend/open_webui/tools/builtin.py 中判断是否需要通过终端读取文件时使用了如下条件:

# line 482 (edit_image)
if url.startswith('/') and not url.startswith('/api/v1/files/'):
    data = await get_terminal_file(...)

# line 578
if image_url and image_url.startswith('/') and not image_url.startswith('/api/v1/files/'):

Windows 绝对路径以盘符开头(C:/... 或 C:\...),不以 / 开头,因此不进入 get_terminal_file 分支,而是被原样转发给图片服务方,图片服务把它当作 URL 去请求,得到 404。模型通常会拿同一路径重试,然后放弃。

旁证:同仓库 utils/terminals.py:643 已使用 posixpath.isabs(home) or ntpath.isabs(home) 来兼容 Windows 绝对路径,说明 Windows 盘符路径在本项目中确实需要单独处理。Issue 中关联的 #31340 也报告了 POSIX-only 绝对路径判断在 Windows 上误判的问题。

环境排查

  • 确认 Open WebUI 版本是否为 v0.13.4 或目标版本,并核对 tools/builtin.py 中两处路径判断是否仍为 startswith('/') 形式。
  • 确认终端环境:Open Terminal 版本(Issue 中为 0.17.x)、操作系统(Windows 11)、接入方式(Tether 中继)。
  • 确认聊天设置中 Chat Uploads 是否为 Filesystem,以及是否已选中 Windows 终端。
  • 确认 Image Generation 与 Image Edit 已开启,且所用连接支持图片编辑。
  • 对比验证:同一图片以 /api/v1/files/... URL 传入是否成功;从 Linux/macOS 终端传入是否成功。若两者都成功,说明问题集中在 Windows 路径判断上。
  • Issue 未提供 Python、CUDA、PyTorch、显卡型号等版本信息,无需据这些项下结论。

解决步骤

  1. 复现并确认失败路径:连接 Windows 终端,开启 Image Edit,选中该终端并附加 JPG,请求“edit this image: make the door blue”,观察工具调用参数中的 image_urls 是否为 C:/... 形式,并确认返回 {"error":"404: We could not find what you're looking for :/"}。
  2. 对照源码:打开 backend/open_webui/tools/builtin.py,确认第 482 行附近(edit_image)和第 578 行附近(display_file 风格图片路径)仍只使用 startswith('/') 判断。
  3. 可优先尝试的修改(尚未验证):将两处判断替换为能识别 Windows 绝对路径的共享 helper,例如 Issue 中给出的:
def _is_terminal_path(value: str) -> bool:
    if value.startswith('/api/v1/files/') or '://' in value or value.startswith('data:'):
        return False
    return posixpath.isabs(value) or ntpath.isabs(value)
  1. 在修改处引入 posixpath 与 ntpath(或复用 utils/terminals.py 中已有的判断方式),保证 /api/v1/files/、URL 和 data: 仍被排除,不进入终端读取分支。
  2. 重新构建或重启 Open WebUI 容器,使改动生效。
  3. 若不具备改源码条件,可先用 /api/v1/files/... 形式的图片 URL 完成编辑任务作为临时替代,但这不解决 Windows 终端路径本身的问题。

验证方法

在同样的 Windows 终端与 Chat Uploads = Filesystem 配置下,再次让模型编辑同一张本地 JPG。若工具通过终端读取到文件、编辑正常返回结果且不再出现 404,说明问题已解决。同时回归检查以 /api/v1/files/... URL 和 data: 形式传入图片仍能正常工作,确认新增的路径判断没有把这两类输入误判为终端路径。

参考来源

open-webui/open-webui #34719

Issue 中关联讨论:#33067、#33824、#31340、#22352。

GamsGo AI

AI 工具推荐

想把多个 AI 模型放在一个入口?

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 36541

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注