Hermes Desktop 下载安装教程(2026):Windows/macOS 桌面版安装、接入国内模型与首次上手
TL;DR: Hermes Desktop 是 Hermes Agent 的官方桌面客户端,和命令行版共用同一套配置、会话、技能和记忆,只是把终端换成了图形界面。Windows 11 22H2 及以上直接装 MSIX 包;Windows 10 先跑 PowerShell 安装脚本,再执行
hermes desktop。macOS 只支持 Apple Silicon。装完在 Settings → Providers 填 API Key、Settings → Model 选主模型即可开聊。国内模型优先选带-cn的提供商,其他平台用 Custom Endpoints 填base_url。
如果你已经按 Hermes 安装与使用教程 装过命令行版,桌面版不用重装,直接运行 hermes desktop 就能打开。完全没装过的,也从这篇开始:它会告诉你哪条安装路径适合你的系统,以及怎么把国内的模型 Key 接进去。
📚 本文目录(点击跳转)
- 一、桌面版和命令行版是什么关系
- 二、安装前:系统要求与两条安装路径
- 三、Windows 11:用 MSIX 安装包(推荐)
- 四、Windows 10:用 PowerShell 脚本安装
- 五、macOS 与 Linux 怎么装
- 六、首次启动与模型配置
- 七、接入国内模型:原生提供商与自定义端点
- 八、桌面版日常使用与进阶功能
- 九、更新、卸载与常见报错
- Hermes 桌面版方案的优缺点分析
- 适合人群与适用场景
- 常见问题 FAQ
- 相关教程
一、桌面版和命令行版是什么关系
很多人以为桌面版是另一个产品,其实不是:
| 对比项 | 命令行版(hermes) | 桌面版(Hermes Desktop) |
|---|---|---|
| 内核 | 同一个 Agent | 同一个 Agent |
| 配置文件 | config.yaml | 同一份 |
| API Key | .env / 设置 | 同一份 |
| 会话、技能、记忆 | 共享 | 共享 |
| 操作方式 | 终端输入命令 | 图形界面点选 |
也就是说,你在终端里配好的模型,打开桌面版就能直接用;在桌面版里新建的会话,回到终端 hermes --resume 也能接着聊。桌面版只是多了一个更顺手的壳:流式工具输出、并排预览、文件浏览器、内置终端、Git 审阅、语音、定时任务和技能管理都能点出来。
数据目录默认是:
- Windows:
%LOCALAPPDATA%\hermes - macOS / Linux:
~/.hermes
NOTE
别同时开两个网关。桌面版自带本地后端,命令行也可以启动网关。同一个模型凭据、同一个消息平台应用,同一时间只应该有一个网关在跑,否则会互相抢连接。
二、安装前:系统要求与两条安装路径
| 系统 | 推荐方式 | 关键限制 |
|---|---|---|
| Windows 11 22H2 及以上 | 官网下载 .appinstaller(MSIX) | 系统版本不够会装不上 |
| Windows 10 | PowerShell 安装脚本 + hermes desktop | 没有官方 MSIX 包,首次构建较慢 |
| macOS | 官网下载 DMG | 仅 Apple Silicon,Intel Mac 不支持桌面版 |
| Linux | 源码安装后 hermes desktop | 官方发布流程不提供 Linux 桌面包 |
两个通用前提:
- 网络能访问 Hermes 的安装源和模型 API。安装包本身自带 Python、Node 和依赖,但模型调用要联网。
- 预留几个 GB 磁盘。源码安装要放运行时、依赖和桌面构建产物。
三、Windows 11:用 MSIX 安装包(推荐)
- 打开 Hermes 官网,下载 Windows 版安装包;
- 双击下载下来的
.appinstaller文件,交给 Windows App Installer 处理; - 按提示确认安装。它会装一个签名的 MSIX 包,并记录后续更新的来源;
- 从开始菜单启动 Hermes。
MSIX 包的好处是开箱即用:Python、Node、依赖和界面都是预构建的,第一次启动不需要编译,也不会往你的用户目录里克隆源码。它还会注册 hermes、hermes-agent、hermes-acp 三个命令别名,装完之后终端里照样能用。
WARNING
Windows 10 装不了这个包。MSIX 桌面包要求 Windows 11 22H2 或更高;Windows 10 请走下一节的脚本安装。强行双击只会得到系统版本不满足的提示。
如果系统里已经有别的 Hermes 安装,命令别名可能被遮住。用 Get-Command hermes -All 看实际指向,或在「设置 → 应用 → 高级应用设置 → 应用执行别名」里调整。
四、Windows 10:用 PowerShell 脚本安装
打开 PowerShell(或 Windows Terminal),执行:
iex (irm https://hermes-agent.nousresearch.com/install.ps1)官方脚本不要求管理员权限,装到 %LOCALAPPDATA%\hermes\,并把 hermes 加进当前用户的 PATH。旧版教程里要求用管理员 PowerShell,现在的官方脚本已经不需要;万一遇到权限错误,再以管理员身份重开窗口重跑即可。
装完关掉窗口重新打开,新 PATH 才会生效。
如果想让脚本顺便构建桌面版并创建开始菜单、桌面快捷方式:
& ([scriptblock]::Create((irm https://hermes-agent.nousresearch.com/install.ps1))) -IncludeDesktop已经装过命令行版、当时没加这个参数,也可以后补:
hermes desktop第一次运行会构建桌面界面,需要联网下载依赖,耗时通常比 MSIX 长。构建完成后,以后启动就快了。
验证安装:
Get-Command hermes
hermes --versionTIP
安装脚本可以重复运行。卡在下载依赖时,先确认网络能到 GitHub 和 Hermes 的下载源,再重跑一次,不需要先卸载。
五、macOS 与 Linux 怎么装
macOS:从官网下载 DMG,打开后把 Hermes.app 拖进「应用程序」。只支持 Apple Silicon(M 系列);Intel Mac 不在支持范围内。
首次打开如果被 Gatekeeper 拦住,到「系统设置 → 隐私与安全性」里允许一次。
Linux:官方发布流程没有 Linux 桌面安装包。可以先用安装脚本装命令行版:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash再运行 hermes desktop 从源码构建桌面版。需要系统有构建依赖和可用的图形环境;构建失败时按终端提示补依赖,或继续用命令行版。
六、首次启动与模型配置
第一次打开桌面版会出现引导页。你可以:
- 直接登录 Nous Portal(官方订阅网关,一个账号覆盖多家模型);
- 或者选 Choose provider later,先进应用,之后再配。
对大多数国内用户,推荐第二条:先把界面跑起来,再填自己的 Key。
第一步:在 Providers 里加凭据
打开 Settings → Providers,这一页分三块:
- Accounts:OAuth 登录类提供商(Nous Portal、Grok、Qwen OAuth 等);
- API keys:填 API Key 的提供商;
- Custom Endpoints:任何 OpenAI 兼容的服务。
在 API keys 里找到你的提供商,粘贴 Key 保存。保存后这个提供商才会出现在模型选择器里——Hermes 只列已认证的提供商。
第二步:设置主模型
打开 Settings → Model:
- 在 Main model 那一行选择提供商和模型;
- 点下面的 Apply;
- 回到聊天,新建一个会话。
设置里改的是每份配置的默认模型,只对新会话生效。当前已经打开的聊天要保持原模型,想立刻换就在输入框左侧的模型选择器里点,或者在对话里发 /model。
第三步:验证
发一句「你好」,能正常流式回复就说明接通了。底部状态栏能看到当前模型、上下文占用比例;如果报错,桌面版会直接指出是哪一层失败:提供商、端点、认证、计费、网关还是本地运行时,比终端里的一行报错好排查得多。
七、接入国内模型:原生提供商与自定义端点
Hermes 已经内置了一批国内提供商,不用绕 OpenRouter:
| 提供商 | 环境变量 | 提供商 ID | 说明 |
|---|---|---|---|
| DeepSeek | DEEPSEEK_API_KEY | deepseek | 官方 API |
| 智谱 GLM | GLM_API_KEY | zai | 自动探测可用端点 |
| Kimi / Moonshot(国内) | KIMI_CN_API_KEY | kimi-coding-cn | 走 api.moonshot.cn |
| MiniMax(国内) | MINIMAX_CN_API_KEY | minimax-cn | 国内端点 |
| 通义千问 / 阿里云百炼 | DASHSCOPE_API_KEY | alibaba / alibaba-cn | DashScope,国内用 -cn |
两种接法选一种即可。
接法一:在桌面界面里填(推荐)
- Settings → Providers → API keys,选对应提供商,粘贴 Key;
- Settings → Model → Main model,选提供商和模型,点 Apply;
- 新建会话验证。
界面里填的 Key 会按当前配置保存,之后命令行版也能用。
接法二:写进 .env
Windows 路径是 %LOCALAPPDATA%\hermes\.env,macOS/Linux 是 ~/.hermes/.env:
DEEPSEEK_API_KEY=sk-xxx
GLM_API_KEY=xxx
KIMI_CN_API_KEY=xxx
MINIMAX_CN_API_KEY=xxx
DASHSCOPE_API_KEY=xxx写完后重启桌面版,再到 Settings → Model 里选模型。Kimi、MiniMax、通义这类分国内外端点的提供商,国内网络要选带 -cn 的那一项;用国际端点可能因网络或账号区域不匹配而失败。
接法三:Custom Endpoints 接其他平台
硅基流动、火山方舟、自建网关这类没有内置条目的服务,用 Settings → Providers → Custom Endpoints:
- 填一个名字和
base_url(通常以/v1结尾); - API Mode 选
Chat Completions,不确定就先用Auto-detect; - 填 API Key,点 Test;
测试通过后,在 Settings → Model 的列表里选它。
NOTE
主模型不带视觉时,单独配视觉模型。DeepSeek、Kimi 这类编程模型不一定支持图片输入。到 Settings → Model → Auxiliary models 把 Vision 指向一个支持视觉的模型,否则截图和图片分析会失败。标题生成、上下文压缩这些辅助任务也可以指向更便宜的模型,省 token。
八、桌面版日常使用与进阶功能
装好之后,这些是命令行里不直观、桌面版点两下就有的能力:
- 聊天与工具输出:工具调用过程流式展开,能点开看细节;右侧预览栏可以一边聊一边看网页、文件或渲染结果。
- 文件浏览器与项目:左侧可以直接浏览目录、打开项目;它会扫描本地 Git 仓库,按项目组织会话。
- 内置终端:不用切窗口,在应用里跑命令,输出直接贴回对话。
- Git 审阅:查看改动、按文件审阅,配合 Agent 做提交前检查。
- 记忆图谱:在对话里发
/journey,看它学到过哪些技能和记忆,可以逐条编辑或删除。 - 语音:输入框旁的麦克风是听写,悬停还能打开「朗读回复」和唤醒词;完整语音对话在右侧主按钮。
- 定时任务:Scheduled Jobs 里管理 cron,任务结果可以推到飞书、Telegram 等消息平台。
- 技能:Skills 页浏览、安装、启用或禁用技能,内置可选技能一键装。
- Bot Mode:每个配置(profile)以「机器人」的形式出现,各自有会话和固定例程,适合把工作、生活、写作拆开。
- 远程网关:Settings → Gateways 可以连另一台机器上的 Hermes,把重活放到服务器上跑。
IMPORTANT
安全边界:桌面版本地后端以你的系统账号运行,能执行命令、读写文件、访问环境变量里的密钥。不要把它暴露到公网;需要远程访问就用 SSH 隧道、Tailscale 这类可信网络,或者在 Settings 里开启认证后再绑定到非回环地址。
九、更新、卸载与常见报错
更新
- MSIX 安装:用应用内的更新按钮,或 Windows App Installer 检查更新;
- 源码安装:
hermes update,桌面版会跟着更新; - 更新后图标消失:先重跑
hermes update;还不行执行hermes desktop --build-only --force-build手动重建。
卸载
- MSIX:Windows「设置 → 应用 → 已安装的应用」里卸载;
- 源码安装:打开 Settings → About → Danger zone 选择卸载范围,或在终端执行
hermes uninstall --gui(只删桌面界面)、hermes uninstall(连 Agent 一起删、保留数据)、hermes uninstall --full(数据也清空)。不确定就先加--dry-run看清单。 - 不管哪种方式,不要为了修问题直接删数据目录(Windows 是
%LOCALAPPDATA%下的 hermes 文件夹),那会连配置、凭据和会话一起删掉。
常见报错对照
| 现象 | 原因 | 处理 |
|---|---|---|
| 双击 MSIX 提示系统版本不满足 | Windows 10 或低于 11 22H2 | 改用 PowerShell 脚本安装 |
| 首次启动白屏、很慢 | 源码版正在构建前端 | 等构建完成;看 logs/desktop.log |
| 提示本地后端停止工作 | 后端进程崩了 | 应用会自动重启;连续崩溃看日志里的 traceback |
| 模型列表里找不到某家 | 该提供商还没认证 | 去 Providers 填 Key 或加自定义端点 |
| 换了默认模型但当前聊天没变 | 默认值只对新会话生效 | 在输入框模型选择器里切换,或发 /model |
| 截图/图片分析失败 | 主模型不支持视觉 | 到 Auxiliary models 里给 Vision 单独指定模型 |
| 消息平台收不到回复 | 网关没在跑 | hermes gateway status,再 hermes gateway restart |
| 远程连接超时 | SSH 或网络慢 | 检查服务器地址、认证和网络;官方文档给了超时配置 |
Hermes 桌面版方案的优缺点分析
优点
- 零终端门槛:安装、配模型、开网关都能点选完成
- 功能密度高:预览、文件浏览器、终端、Git、语音、定时任务集中在一个窗口
- 和命令行完全互通:配置、会话、技能、记忆共用,不用二选一
- 报错更具体:失败时会指出是提供商、认证、计费还是网关的问题
- 支持远程后端:界面在本地,重活可以放服务器
不足
- Windows 10 没有 MSIX 包:只能源码安装,首次构建慢
- macOS 仅 Apple Silicon:Intel Mac 用不了
- 不是常驻服务:电脑关机、休眠、退出应用就停
- 占用资源更高:Electron 界面比终端吃内存
- 版本迭代快:界面路径和选项会变,以实际版本为准
适合人群与适用场景
适合你,如果:
- 不想记命令,希望用图形界面完成配置和日常对话
- 要在多个项目、多个会话之间来回切,终端标签不够用
- 需要一边聊一边看网页、文件、终端输出
- 手里有国内模型的 API Key,想快速接进去
不适合你,如果:
- 只用 Windows 10 且不想等首次构建:命令行版更轻
- 需要 7×24 在线的消息机器人:应该部署到服务器
- 机器内存紧张:Electron 界面比终端占资源
- 只想跑脚本、做自动化:命令行版和 cron 更直接
常见问题 FAQ
Windows 10 能装 Hermes 桌面版吗?
桌面版和命令行版需要装两份吗?
一定要登录 Nous Portal 才能用吗?
国内模型怎么接?
在设置里换了模型,当前聊天怎么没变?
首次启动很慢、白屏或者一直转圈?
更新之后桌面版图标不见了?
桌面版能连另一台服务器上的 Hermes 吗?
桌面版能代替服务器常驻吗?
相关教程
- Hermes 安装与使用教程 — 命令行版的 Windows 一键安装、模型配置与排错
- Hermes 接入飞书教程 — 官方接口、无需公网 IP,把助手放进工作群
- Hermes 接入微信教程 — 个人微信入口的扫码配置与风控提示
- Hermes 教程专栏 — 模型版本、上手流程和全部接入教程
