快速结论:当 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、显卡或浏览器版本信息,无需作为必查项。
解决步骤
- 先复现并确认返回的
home值。按 Issue 的复现步骤:在 Windows 主机上运行 Open Terminal 0.12.4 或更新版本,在home目录放入AGENTS.md,附加终端并发送消息,观察文件是否被注入聊天。 - 定位
backend/open_webui/utils/terminals.py中get_terminal_agents_md()的路径判断部分,确认当前只使用posixpath.isabs(home)做校验。 - 可优先尝试 Issue 中提交者给出的补丁思路:引入
ntpath,先判断posixpath.isabs(home)并用posixpath.join拼接;否则再判断ntpath.isabs(home)并用ntpath.join拼接;两者都不满足时仍返回None。POSIX 分支保持在前,避免改变 Linux/macOS 行为。 - 按 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、空值或缺失仍跳过。 - 应用修改后重新启动 Open WebUI,再按相同步骤附加 Windows 终端并发送消息。
验证方法
重新发送消息后,AGENTS.md 内容应被流式注入聊天。如果仍被跳过,检查补丁后的分支是否对当前 home 返回了拼接后的路径,以及 /files/read 请求是否真的带有该路径。Issue 中仅说明提交者确认“修复有效,且未发现对其他终端行为的影响”,未提供完整日志验证细节,因此以上验证以聊天侧是否收到 AGENTS.md 为准。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。

![[Refactor/Chore] Add preflight workflow validation and actionable diagnostics for missing variable references / unreachable paths](https://www.chat-gpts.plus/wp-content/uploads/2026/09/34358-5d0ee5cc-768x403.jpg)
