issue: Terminal AGENTS.md is silently skipped on Windows Open Terminal hosts (`posixpath.isabs` rejects drive-letter home)

当 Open WebUI 挂载的 Open Terminal 运行在 Windows 主机上时,终端 AGENTS.md 功能会因为路径判断失败而被静默跳过,聊天里看不到 AGENTS.md 内容。优先排查 get_terminal_agents_md() 中对 /files/cwd 返回的 hom

快速结论:当 Open WebUI 挂载的 Open Terminal 运行在 Windows 主机上时,终端 AGENTS.md 功能会因为路径判断失败而被静默跳过,聊天里看不到 AGENTS.md 内容。优先排查 get_terminal_agents_md() 中对 /files/cwd 返回的 home 的绝对路径判断是否只用了 posixpath.isabs。

适用环境:Open WebUI v0.11.4(Docker 方式安装);宿主机为 Ubuntu 24.04.5 LTS;附带的 Open Terminal 0.12.4 或更新版本,运行在 Windows 主机上并通过 winsw 加载 Python 环境。Issue 未提供 CUDA、显卡、Ollama 版本等信息。

最快修复方案:暂无确认的一步修复方案。Issue 中给出的方案(补丁)是在 backend/open_webui/utils/terminals.py 中同时使用 ntpath 判断 Windows 绝对路径,并按其路径风格拼接 AGENTS.md,但该补丁由提交者自行验证,尚未作为官方修复步骤确认。

注意事项:补丁中 POSIX 分支先执行,理论上不影响 Linux/macOS 行为;C:relative、relative/path、空值或缺失值仍会被跳过(行为不变)。由于该修复属于用户自行提供的改动,正式合并前需自行承担修改核心代码的风险,并确认与后续版本兼容。

问题场景

用户在 Open WebUI v0.11.4 中挂载了运行在 Windows 主机上的 Open Terminal(0.12.4 或更新版本,通过 winsw 加载 Python 环境)。终端 AGENTS.md 功能(v0.11.4 引入,涉及 commits 946be432 / f6922a4c)不会加载文件。把 AGENTS.md 放到 /files/cwd 报告的 home 目录(例如 C:\ProgramData\OpenTerminal\<instance>)后,在聊天中附加该终端并发送消息,AGENTS.md 不会被流式注入聊天;除非通过工具调用直接读取磁盘,否则文件等于未读取,且 debug 级别也没有任何日志。

报错原文

issue: Terminal AGENTS.md is silently skipped on Windows Open Terminal hosts (`posixpath.isabs` rejects drive-letter home)

>>> import posixpath
>>> posixpath.isabs(r"C:\ProgramData\OpenTerminal\inst")
False
>>> posixpath.isabs("C:/ProgramData/OpenTerminal/inst")
False

原因分析

最可能的原因是路径判断逻辑只兼容 POSIX 风格。Open Terminal 返回的 home 使用宿主机的原生格式,因此在 Windows 上会是盘符路径(如 C:\...)或 UNC 路径(如 \\server\share\...)。backend/open_webui/utils/terminals.py 中的 get_terminal_agents_md() 用 posixpath.isabs(home) 判断绝对路径,对 Windows 路径返回 False,函数提前返回 None,既不会读取文件,也不会输出日志。

环境排查

  • 确认 Open WebUI 版本为 v0.11.4,并确认终端 AGENTS.md 功能所对应的代码分支/提交(946be432 / f6922a4c)已包含在运行版本中。
  • 确认 Open Terminal 版本为 0.12.4 或更新,使 /files/cwd 返回 home 字段。
  • 确认 Open Terminal 实际运行在 Windows 主机上(例如通过 winsw 加载),而不是 Linux 容器内。
  • 确认 home 的实际格式:盘符路径(C:\...)或 UNC 路径(\\server\share\...)。
  • Issue 未提供 Ollama、CUDA、PyTorch、显卡或浏览器版本信息,无需作为必查项。

解决步骤

  1. 先复现并确认返回的 home 值。按 Issue 的复现步骤:在 Windows 主机上运行 Open Terminal 0.12.4 或更新版本,在 home 目录放入 AGENTS.md,附加终端并发送消息,观察文件是否被注入聊天。
  2. 定位 backend/open_webui/utils/terminals.py 中 get_terminal_agents_md() 的路径判断部分,确认当前只使用 posixpath.isabs(home) 做校验。
  3. 可优先尝试 Issue 中提交者给出的补丁思路:引入 ntpath,先判断 posixpath.isabs(home) 并用 posixpath.join 拼接;否则再判断 ntpath.isabs(home) 并用 ntpath.join 拼接;两者都不满足时仍返回 None。POSIX 分支保持在前,避免改变 Linux/macOS 行为。
  4. 按 Issue 的补丁说明核对各类 home 的预期结果:/home/user 得到 /home/user/AGENTS.md;C:\ProgramData\OpenTerminal\inst 得到 C:\ProgramData\OpenTerminal\inst\AGENTS.md;\\server\share\home 得到 \\server\share\home\AGENTS.md;C:relative、relative/path、空值或缺失仍跳过。
  5. 应用修改后重新启动 Open WebUI,再按相同步骤附加 Windows 终端并发送消息。

验证方法

重新发送消息后,AGENTS.md 内容应被流式注入聊天。如果仍被跳过,检查补丁后的分支是否对当前 home 返回了拼接后的路径,以及 /files/read 请求是否真的带有该路径。Issue 中仅说明提交者确认“修复有效,且未发现对其他终端行为的影响”,未提供完整日志验证细节,因此以上验证以聊天侧是否收到 AGENTS.md 为准。

参考来源

open-webui/open-webui #31340

GamsGo AI

AI 工具推荐

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

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

了解 GamsGo AI

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

这个方案解决了吗?

celebrityanime
celebrityanime
文章: 25551

发表回复

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