Hermes Desktop 初体验极简安装指南Hermes Desktop 是 Hermes Agent 的桌面客户端——和终端里用的hermes是同一个 agent术语解释Agent具备自主性、能调用工具以完成目标的 AI 程序。Agent 是一种基于大语言模型的智能程序能够感知环境、做出决策、调用工具执行操作并自主推进任务。共享配置、API Key、会话、技能和记忆。你在终端开的会话桌面端能接着聊桌面端的设置终端也能看到。支持 Windows、macOS、Linux 三大平台。本文以Windows 原生安装为例。前置条件在安装 Desktop 之前需要先完成 Hermes CLI 的安装详见《Hermes CLI Windows 安装与模型配置指南》项目要求Hermes CLI已安装hermes --version正常输出Node.js≥ 18CLI 安装时已自动配备模型配置已配置至少一个模型提供商DeepSeek / MiMo 等第一步设置国内镜像下载安装前先设置环境变量让 Electron 直接从国内镜像下载绕过 GitHub$env:ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/$env:CSC_IDENTITY_AUTO_DISCOVERY false环境变量作用ELECTRON_MIRROR指定 Electron 国内镜像地址npmmirror约 114MB 从此下载CSC_IDENTITY_AUTO_DISCOVERY设为false跳过 Windows 代码签名个人使用无需签名建议写入 PowerShell profile 永久生效以后每次打开终端自动生效Add-Content$PROFILE$env:ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/Add-Content$PROFILE$env:CSC_IDENTITY_AUTO_DISCOVERY false第二步构建桌面应用设置好镜像后直接运行hermes desktop--force-build如果之前安装失败过加--force-build强制重新构建会清除缓存重新下载。首次安装也建议加上此参数。构建过程的四个步骤步骤操作预期耗时说明1安装 npm 依赖约 1 分钟安装 1295 个 npm 包2构建前端Vite约 20 秒打包 React 界面生成 dist/3下载 Electron 二进制约 1-3 分钟约 114MB从国内镜像下载4electron-builder 打包约 1 分钟生成Hermes.exe可执行文件全部完成后桌面应用会自动启动。构建产物路径桌面应用构建完成后可执行文件位于%LOCALAPPDATA%\hermes\hermes-agent\apps\desktop\release\win-unpacked\Hermes.exe目录中包含 Electron 外壳、依赖库DLL、资源文件等总共约 204 MB其中Hermes.exe本身约 200 MB。启动桌面应用方式一从 CLI 启动hermes desktop如果已经构建过后续启动不需要--force-build直接运行即可。方式二双击桌面快捷方式推荐创建桌面快捷方式以后双击即开$hermesExe$env:LOCALAPPDATA\hermes\hermes-agent\apps\desktop\release\win-unpacked\Hermes.exe$desktopPath[Environment]::GetFolderPath(Desktop)$wshNew-Object-ComObject WScript.Shell$shortcut$wsh.CreateShortcut($desktopPath\Hermes Desktop.lnk)$shortcut.TargetPath $hermesExe$shortcut.WorkingDirectory $env:LOCALAPPDATA\hermes\hermes-agent\apps\desktop\release\win-unpacked$shortcut.Description Hermes Agent 桌面客户端$shortcut.Save()快捷方式创建后也可以右键 →「固定到任务栏」以后一键打开。方式三开始菜单启动运行上面的快捷方式创建命令后开始菜单中也会出现Hermes Desktop直接搜索即可。常见问题排查问题解决方案构建卡在 “Build desktop app”设置ELECTRON_MIRROR后--force-build重建报错 “ENOENT rename electron → Hermes”清除 Electron 缓存 半成品重新构建构建成功后白屏重置.hermes-bootstrap-complete或重建 venv桌面端与 CLI 配置不一致运行hermes doctor检查配置状态npm install 很慢切换 npm 镜像源到 npmmirror如何更新hermes updatehermes desktop如何卸载hermes uninstall --guiQ1: 构建卡在 “Build desktop app” 步骤原因Electron 二进制下载被 GitHub 网络限制。解决确保已设置ELECTRON_MIRROR然后强制重建$env:ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/hermes desktop--force-buildQ2: 报错 “ENOENT … rename ‘…/win-unpacked/electron’ - ‘…/win-unpacked/Hermes’”原因之前下载的 Electron zip 文件损坏解压后缺少二进制文件。解决清除缓存后重建# 清除 Electron 下载缓存Remove-Item$env:LOCALAPPDATA\electron\Cache\electron-*.zip-Force-ErrorAction SilentlyContinue# 清除半成品构建Remove-Item$env:LOCALAPPDATA\hermes\hermes-agent\apps\desktop\release\*unpacked-Recurse-Force-ErrorAction SilentlyContinue# 重新构建$env:ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/hermes desktop--force-buildQ3: 构建成功但启动后白屏原因通常是首次启动引导状态异常或 Python 虚拟环境损坏。解决# 第一步查看桌面应用日志定位具体错误hermes logs gui-f# 第二步重置首次启动状态Remove-Item$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete-Force-ErrorAction SilentlyContinue# 第三步如果日志报 Python 相关错误重建虚拟环境Remove-Item$env:LOCALAPPDATA\hermes\hermes-agent\venv-Recurse-Force-ErrorAction SilentlyContinue hermes desktop--force-buildQ4: 桌面端与 CLI 配置不一致原因Desktop 和 CLI 共享%LOCALAPPDATA%\hermes\下的同一套配置。如果配置在 Desktop 构建后被修改过可能出现不一致。解决hermes doctor# 检查当前配置状态hermes config check# 检查缺失配置项然后在桌面端 Settings 中检查模型选择是否与 CLI 一致。Q5: npm install 很慢原因npm 默认从 registry.npmjs.org 下载国内访问较慢。解决切换 npm 镜像源npm configsetregistry https://registry.npmmirror.comQ6: 如何更新 Desktophermes update# 更新 CLI 和核心代码到最新版hermes desktop# 重新构建桌面应用自动检测新版本Q7: 如何卸载 Desktophermes uninstall--gui# 移除 GUI 构建产物和 node_modules如果需要完全移除 Hermes包括 CLIRemove-Item$env:LOCALAPPDATA\hermes-Recurse-Force从源码开发模式运行可选如果你需要修改桌面应用本身可以从源码启动开发服务器# 进入桌面应用目录cd$env:LOCALAPPDATA\hermes\hermes-agent\apps\desktop# 启动开发模式Vite 热更新 Electron 实时预览npm run dev开发模式下代码修改会自动热更新适合调试和定制界面。让你的 Agent 自动完成配置如果你电脑上已经有其他 Agent术语解释Agent具备自主性、能调用工具以完成目标的 AI 程序。Agent 是一种基于大语言模型的智能程序能够感知环境、做出决策、调用工具执行操作并自主推进任务。 了如 Claude Code、Trae、Cursor、Qoder 等可以让它按照本文档的步骤自动帮你构建 Desktop。方式一最简单把本文档的文件路径或链接发给你的 Agent让它自己阅读并执行。方式二更精准推荐直接把下面这段话复制给你的 Agent请根据这篇 Hermes Desktop 安装指南帮我完成桌面应用的构建和配置 文档路径D:\笔记\Agent工具搭建\Hermes Desktop 桌面应用安装指南.md 需要完成的内容 1. 设置 ELECTRON_MIRROR 国内镜像环境变量 2. 运行 hermes desktop --force-build 构建桌面应用 3. 创建桌面快捷方式 4. 验证构建产物是否存在release\win-unpacked\Hermes.exe 5. 启动桌面应用 注意构建过程中 Electron 二进制约 114MB从 npmmirror 国内镜像下载。 如果你的 Agent 支持 MCP术语解释MCPModel Context ProtocolAnthropic 提出的开放标准用于将 AI 应用连接到外部数据源与工具。也可以先接入 Hermes 中文文档 MCP Serverhttps://mcp.hermesagent.org.cn/v1让 Agent 直接检索最新文档来指导构建。快速参考完整 TL;DR# 1. 设置国内镜像$env:ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/$env:CSC_IDENTITY_AUTO_DISCOVERY false# 2. 构建桌面应用hermes desktop--force-build# 3. 创建桌面快捷方式$hermesExe$env:LOCALAPPDATA\hermes\hermes-agent\apps\desktop\release\win-unpacked\Hermes.exe$wshNew-Object-ComObject WScript.Shell$shortcut$wsh.CreateShortcut($([Environment]::GetFolderPath(Desktop))\Hermes Desktop.lnk)$shortcut.TargetPath $hermesExe$shortcut.Save()# 4. 启动双击桌面图标或在终端运行hermes desktop参考与延伸阅读如果你对 AI Agent 的搭建和配置感兴趣欢迎关注我的 CSDN 专栏更多实战经验持续更新中文章简介从小白到大神MiMo Code 配置与使用零基础通关秘籍小米 MiMo Code 终端 AI 编程助手的完整安装、配置、使用教程含 Web 图形界面VS Code 安装 Claude Code 并接入 DeepSeek V4 Model在 VS Code 中配置 Claude Code 并接入 DeepSeek V4 模型的完整流程使用 Reasonix 接入 DeepSeek从零搭建你的 AI 编程助手基于 Reasonix 框架从零搭建 AI 编程助手的实战教程