RuntimeError: Terminal server ‘http://localhost:4001’ not found

问题场景

用户在 Open WebUI 中通过聊天界面的终端工具连接本地 terminal server 时失败。该终端是用户在「设置 → 集成」中自行添加的直连连接（URL 为 http://localhost:4001），而非系统管理员配置的连接。侧边栏的文件管理器功能正常，问题仅影响终端连接。

报错原文

RuntimeError: Terminal server 'http://localhost:4001' not found

原因分析

这是 v0.11.0 的回归缺陷。前端代码（Chat.svelte）在传递用户直连终端时，将 URL 作为 terminal_id 无条件发送。后端在解析 terminal_id 时，仅查询系统级连接列表（通过 ID 匹配），因此直连终端的 URL 永远无法匹配。v0.10.2 前此错误会被静默忽略（终端仍通过独立客户端路径 tool_servers 工作），v0.11.0 加强了校验，直接抛出异常并导致聊天中断。

环境排查

• 确认 Open WebUI 版本是否为 v0.11.0（此版本存在该回归）。
• 确认终端连接类型：用户直连连接（URL 形式）还是系统管理员配置的连接（ID 形式）。
• 若使用 Docker，检查容器镜像标签及启动参数，确认未覆盖关键环境变量。
• 可检查浏览器控制台和 Docker 容器日志，确认是否只有终端报错而文件浏览器正常。

解决步骤

1. 首选：升级到包含修复的版本。Issue 确认修复已合并至 dev 分支，可拉取 ghcr.io/open-webui/open-webui:dev 镜像测试。官方修复 PR 为 #27628。
2. 临时源码补丁（仅供无法立即升级的场景）：编辑容器内 /usr/local/lib/python3.11/site-packages/open_webui/utils/tools.py，找到 get_terminal_tools 函数约 1325-1326 行，将匹配逻辑从仅按 ID 匹配改为「ID 或 URL 均匹配」：
   connection = next((c for c in connections if c.get('id') == terminal_id or c.get('url') == terminal_id), None)
   同时注释掉原来的 1325 行。
3. 若为 Docker 容器，修改后需重建容器或使用 volumes 映射覆盖文件，并重启 Open WebUI 服务。

验证方法

保存源码修改并重启服务后，回到聊天界面尝试使用终端连接 http://localhost:4001，若能开启交互式终端会话且不再出现 RuntimeError，即表示问题解决。若使用 dev 分支，同样验证终端连接是否正常。

参考来源

open-webui/open-webui #27621

AI 工具推荐

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

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

了解 GamsGo AI

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