Hermes WebUI 扩展入门指南不碰核心代码给 WebUI 加功能【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webuiHermes WebUI 是从网页或手机使用 Hermes Agent 的入口。想给它加自定义面板或换个风格不必 fork 核心仓库。本文讲清 Hermes WebUI 扩展机制的运作方式、扩展环境变量配置以及三步跑通第一个扩展让你不动一行核心代码就能加功能。 一、先划清楚扩展能干什么、不能干什么先给结论扩展是官方刻意留下的一个本地注入面——默认完全禁用只有环境变量指向一个真实存在的目录时才会激活。它的工作方式核心实现在 api/extensions.py用HERMES_WEBUI_EXTENSION_DIR指定一个本地目录目录里的文件通过/extensions/路径对外提供。注意这条路由是登录门控的不像/static/那样匿名可达HERMES_WEBUI_EXTENSION_STYLESHEET_URLS声明同源 CSS注入到页面headHERMES_WEBUI_EXTENSION_SCRIPT_URLS声明同源 JS注入到页面/body之前。所以扩展能做的归纳起来就三件事提供本地静态文件、注入样式、注入脚本。在这之上你的脚本可以调用登录用户可用的所有/api/接口。不能做的红线同样明确不能绕过 WebUI 登录认证——/extensions/路由本身要求登录不能访问配置目录之外的文件不能通过内置注入配置加载第三方域名的脚本或样式只收同源路径不能修改 Hermes Agent 的权限、模型或工具设置——除非走现成的、已鉴权的 API。图 1这是 Hermes WebUI 的会话界面。扩展注入的自定义面板可以挂在这里与核心功能并存互不干扰。 二、三步跑通第一个扩展Hermes WebUI 怎么加新功能最短路径就是下面三步。1. 建目录和两个文件mkdir -p ~/.hermes/webui-extension touch ~/.hermes/webui-extension/app.css ~/.hermes/webui-extension/app.js目录放哪都行但别指向别人也能写入的共享目录——那等于给 WebUI 开了后门。2. 写 app.css 和 app.js 的内容app.css只写你自己新增的样式类名加一个独特前缀比如my-ext-避免和主程序样式打架app.js把代码包在自执行函数里不污染全局命名空间开头用标记元素检查是否已执行防止重复加载。内部逻辑就是常规的 DOM 操作——建一个面板节点、往侧边栏挂按钮、绑定事件全程只加节点不改核心代码。完整实现样板建议直接看官方文档这里只讲写什么、放哪里。3. 配置环境变量并启动export HERMES_WEBUI_EXTENSION_DIR~/.hermes/webui-extension export HERMES_WEBUI_EXTENSION_SCRIPT_URLS/extensions/app.js export HERMES_WEBUI_EXTENSION_STYLESHEET_URLS/extensions/app.css ./start.sh两个容易踩的坑HERMES_WEBUI_EXTENSION_DIR必须指向已存在的目录WebUI 不会替你创建目录不存在就不会有任何注入文件不止一个时用英文逗号分隔例如/extensions/runtime.js,/extensions/app.js。启动后刷新浏览器就能看到新面板了。图 2工作区界面是扩展脚本与后端数据打交道的典型区域文件列表、预览等界面都可以被扩展增强。 三、让扩展和后端对话扩展脚本跑在浏览器里和网页其他部分一样带着登录态所以任何用户能调的/api/接口它都能调。最常见的用法是拉数据、渲染进自己的面板const res await fetch(/api/sessions); const sessions await res.json(); console.log(sessions);以会话列表为例fetch(/api/sessions)返回的 JSON 直接渲染成列表即可。请求带的是当前用户身份如果拿到 401/403多半是没登录或会话过期不是扩展的 bug。 四、扩展不生效按现象对号入座的排障清单遇到 WebUI 扩展不加载、或者加载了但不对劲对照下面几条每条一句原因 一句解法页面毫无变化像没装→ 三个环境变量没配齐或 DIR 指向了不存在的目录。先echo检查变量再确认目录真实存在。控制台报脚本 404 或 MIME 错误→ URL 不在/extensions/、/static/之下或文件名写错。注入地址就是你环境变量里的值不是本地磁盘路径。加载了但样式错乱→ 类名和主程序撞了。加独特前缀、提高选择器特异性。接口返回 401/403→ 未登录或会话过期。重新登录后再试。本地正常、容器里不生效→ 环境变量没传进容器。检查 compose / Dockerfile 里是否导出了这三个变量。再补一句改扩展目录里的文件内容后刷新页面即可生效无需重启只有改环境变量才需要重启。排查时WebUI 日志会记录扩展加载状态浏览器 F12 控制台则是扩展自身输出的第一现场。️ 五、安全四条红线扩展以登录会话的权限运行——能读历史、发消息、改设置所以四条红线要记牢最小权限只调用功能真正需要的 API别顺手多拉输入校验用户输入的数据发往后端前先验证不碰敏感信息密码、密钥不进扩展代码更不进日志定期审计周期性地审一遍扩展代码只启用自己写的或来源你完全信任的扩展。Hermes WebUI 扩展机制本质上就是本地文件 环境变量 同源注入目录归你管激活靠配置核心代码保持干净核心更新时扩展通常只需微调。更多能力清单、manifest 多扩展打包方式和进阶用法见官方文档 docs/EXTENSIONS.md。【免费下载链接】hermes-webuiHermes WebUI: The best way to use Hermes Agent from the web or from your phone!项目地址: https://gitcode.com/GitHub_Trending/he/hermes-webui创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考