Windows Hermes设置了tui之后启动npm报错

hermes Installing TUI dependencies…npminstallfailed.✅ Node dependencies installed. Run: python run_agent.py --helpThe system cannotfindthe path specified.解决方法:设置环境变量:HERMES_TUI_DIRC:\Users\username\AppData\Local\hermes\hermes-agent\ui-tui AI生成经验总结 Hermes TUI 在 Windows 下的环境变量解决法适用环境WindowsPowerShell / Git Bash问题现象运行hermes后 TUI 构建失败但dist/entry.js已生成解决方式使用环境变量HERMES_TUI_DIR绕过构建检查1. 问题描述在 Windows 下执行hermes命令时始终出现以下错误TUI build failed. built D:\Users\username\AppData\Local\hermes\hermes-agent\ui-tui\dist\entry.js The system cannot find the path specified. npm notice run hermes-tui0.0.1 build npm notice run node scripts/build.mjs dist\entry.js 3.5mb ⚠️ ⚡ Done in 170ms关键现象TUI 的entry.js文件实际上已经编译成功3.5 MB。但 Hermes 的后端检测到npm run build返回了非零状态码判定构建失败并终止启动流程。2. 根本原因分析2.1chmod命令在 Windows 上不存在Hermes 的 TUI 前端项目ui-tui在其构建脚本可能是package.json或scripts/build.mjs中包含了一条为 Linux/Unix 系统设计的命令chmodx dist/entry.js在 Windows 原生环境包括 PowerShell 和 CMD中chmod不是合法命令执行会失败。但esbuild/tsc等编译工具已经成功生成了entry.js所以构建产物本身没有问题。2.2 Python 对子进程返回码敏感Hermes 的后端Python通过subprocess调用npm run build并检查返回码返回0→ 认为构建成功继续启动 TUI。返回非0→ 认为构建失败打印TUI build failed并退出。即使entry.js已生成只要npm脚本中的任何一条命令失败整个npm run build就会返回非零码。3. 解决方案探索❌ 方案一修改package.json不适用所有版本在用户提供的ui-tui/package.json中build脚本为build:node scripts/build.mjs没有明显的chmod命令因此无法通过简单删除该命令来修复。❌ 方案二修改build.mjs脚本未实施推测scripts/build.mjs内部可能包含对chmod或exec的调用但未进一步验证。❌ 方案三Git Bash 运行依然失败在 Git Bash 中运行hermes仍报相同错误说明问题不只是 Shell 差异而是 Hermes 后端调用逻辑的问题。✅ 方案四使用环境变量HERMES_TUI_DIR成功Hermes 支持通过环境变量HERMES_TUI_DIR直接指定 TUI 前端目录从而跳过构建检查流程。exportHERMES_TUI_DIRC:\Users\username\AppData\Local\hermes\hermes-agent\ui-tuihermes执行后 TUI 正常启动。4. 根本原因与关键点项目说明问题本质Hermes TUI 构建脚本中包含对 Linux 命令chmod的依赖导致 Windows 下npm run build返回非零码为何entry.js已生成esbuild等编译工具先执行成功生成产物chmod是最后一步失败不影响产物本身为何 Git Bash 也不行Hermes 后端使用 Python 的subprocess调用其返回码判断机制不受 Shell 类型影响只要chmod失败返回码即为非零环境变量生效原理HERMES_TUI_DIR让 Hermes 直接使用已存在的dist/entry.js不再触发npm run build流程5. 最终解决方案永久设置环境变量Windows打开“系统属性” → “高级” → “环境变量”在“用户变量”或“系统变量”中新建变量名HERMES_TUI_DIR变量值C:\Users\username\AppData\Local\hermes\hermes-agent\ui-tui点击“确定”保存。重新打开终端输入hermes即可正常使用 TUI。临时设置仅当前会话# PowerShell$env:HERMES_TUI_DIRC:\Users\username\AppData\Local\hermes\hermes-agent\ui-tui# Git Bash / WSLexportHERMES_TUI_DIRC:\Users\username\AppData\Local\hermes\hermes-agent\ui-tui6. 成功后的检查清单运行hermes后若看到类似以下界面则说明 TUI 已成功启动Hermes TUI vX.X.X [Chat Interface] Type your message...同时可以验证hermes chat能正常进入对话模式hermes gateway能正常启动消息网关hermes doctor能运行健康检查7. 经验总结要点说明跨平台兼容性Hermes 的主战场在 Linux/macOSWindows 下部分构建脚本存在兼容性问题错误信息解读built ... entry.js后紧跟错误说明构建产物成功但脚本后期处理失败环境变量是 debug 利器遇到构建类问题优先检查是否支持通过环境变量跳过或重定向社区解决思路官方 PR #22957 已移除chmod但该修复可能未包含在用户当前使用的版本中8. 参考资料Hermes 官方 GitHub Issues关键词TUI build failed Windows chmodPR #22957移除 Windows 上chmod调用Hermes 环境变量文档HERMES_TUI_DIR用法 记录时间2026-08-21️ 系统Windows 11 / PowerShell 7.x / Git Bash (MINGW64)✍️ 致谢感谢社区开发者们的讨论与贡献以及 Hermes 官方团队对跨平台兼容性问题的关注与修复。