Hermes 最新版保姆级安装教程:从装好到跑通,一篇讲透

大家好，我是码锅。

前几天有小伙伴吐槽 Hermes"不好用"，不管什么原因吧，今天一篇保姆级教程教大家如何正确安装，看看有没有你踩过的坑。

安装过程其实我也没那么顺利，我第一次装的时候，卡了三次，花了快 30 分钟才走通。所以我决定把整个过程从头再走一遍，把每一步、每一个坑都记录下来。

全文很长，讲得很细，耐心看完有惊喜哦～

选方案：你有四种装法

Hermes 不止一种安装方式，总体上分为两大类：

一类是桌面端安装包，跟装普通软件一样，一步两步，是魔鬼的步伐，摩擦摩擦...

另一类是基于终端命令行安装，需要稍微懂点技术。当然了，能看到这篇文章并关注码锅的，肯定都是技术大牛！

以下我整理了一份清单，小伙伴们择一品鉴。

方案	适合谁	推荐度
桌面端双击安装	不想碰命令行	⭐⭐⭐⭐⭐
终端一行命令	macOS / Linux / WSL2	⭐⭐⭐⭐⭐
Windows 原生 PowerShell	Windows 不想装 WSL	⭐⭐⭐⭐
从 GitHub 拉源码	想读代码、二开的开发者	⭐⭐⭐

新手推荐桌面端——双击安装包，全程不敲一条命令，装完就进主聊天界面。

终端命令是进阶，桌面端和终端是同一套系统的两个入口，配置完全互通。

环境要求很宽松：macOS 12+ / Ubuntu 20.04+ / Windows（WSL2 或原生 PowerShell），内存 4GB 就够用。

安装前：你心里要有个底

不管选哪种方案，安装流程里大概率会遇到卡住的情况。毕竟是老外的东西，翻山越海来到你身边也不容易。

整个安装过程，网络不塞的话，大概几分钟解决战斗，如果不畅，你可能会"卡住不动"，对，一动不动是那啥的不动。

方式一：桌面端安装（新手首选）

打开官网hermes-agent.nousresearch.com，找到如下区域（这里因为我是macOS系统，默认显示的是DOWNLOAD FOR MAC OS ，官网会自动根据你的操作系统显示对应版本，点击下载即可）：

将安装包下载到合适的位置后：

Windows：双击 .exe 按引导走完
Mac：双击 .dmg，把 Hermes 拖进"应用程序"文件夹
Linux：装 .deb 或 .AppImage

注意对于mac用户来说，图标拖进“应用程序”不等于已经完成安装，此时打开软件会先检测你本地的相关依赖和服务是否已安装，如果没有会给你一个Install Hermes按钮让你点击安装，如果已经通过CLI安装过，会直接打开聊天主界面。

点击Install Hermes 按钮就会开始一步一步安装。

以下是 Hermes 每一步的安装项目清单。

#	安装项目	简要说明
1	System prerequisites	检查系统前置条件
2	Download Hermes Agent	下载 Hermes Agent
3	Create Python virtual environment	创建 Python 虚拟环境
4	Install Python dependencies	安装 Python 依赖包
5	Install browser-tool dependencies	浏览器自动化工具
6	Install hermes command	配置命令行工具
7	Prepare config and skills	初始化默认配置文件
8	Configure API keys and settings	引导你配置LLM的API密钥
9	Configure gateway service	配置网关服务
10	Build desktop app	构建原生桌面应用
11	Finish install	完成所有安装步骤

桌面端装好，打开后界面就长下面这个样子。

方式二：终端一行命令安装（macOS / Linux）

不想装桌面端，直接在终端跑：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

GitHub 直连慢或者失败的，换中文社区镜像：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

脚本会自动完成：依赖检测（Python 3.10+ / Node.js 18+）→ 拉取程序 → 初始化数据目录 ~/.hermes。

这里科普一下：安装目录和配置目录是分开的。

代码目录重装不影响配置。但是配置文件丢了，你的 Hermes 就等于失忆了，所以定期备份整个 ~/.hermes 目录是有必要的。

安装完毕，在终端输入 hermes 即可启动应用，打开后是下面这个样子。

方式三：Windows 专用安装（别用 curl | bash）

Windows 用户特别注意——网上搜到的 curl | bash 在 Windows 上必挂，有两个原因：

cmd / PowerShell 没有 bash，管道没接收方
即使装 Git Bash，脚本检测到 Windows 会主动拒绝执行

正确姿势：打开 PowerShell，一行命令：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

如果提示"禁止运行脚本"，是执行策略限制问题，先放开。执行下面的命令：

Set-ExecutionPolicy -Scope Process Bypass

然后再跑上面那行命令即可。

装完必须关掉并重开 PowerShell，这样 PATH 中配置的环境变量才会生效。新手最容易漏掉的一步。

重装的话，想装到 D 盘指定路径，可以用 -InstallDir 参数：

iex (irm https://hermes-agent.nousresearch.com/install.ps1) -InstallDir "D:\hermes"

“
“
Windows 原生安装目前官方标注为 Early Beta，CLI 和网关都能跑，个别内嵌终端类功能以 WSL2 为佳。追求稳定就走 WSL2 或桌面端。

怎么确认装好了

跑：

hermes --version

注意：新版用 hermes --version，不是 hermes version。 旧版用 version，新版改成了标准参数。

正常输出：

Hermes Agent v0.20.4 (2026.8.18) · upstream 40643cbaInstall directory: /Users/hu/.hermes/hermes-agentInstall method: gitPython: 3.11.15OpenAI SDK: 2.24.0

看到版本号 = 装好了。

装好了不代表能用了。 接下来这几步才是真正决定你能不能用起来的。

跑环境诊断

hermes doctor

它会给一份完整诊断：

带 ✓ 的是核心功能，全正常。带 ⚠ 的是非必需功能——缺 key 不影响你装好 Hermes 去聊天。

首启配置向导

装完后第一次跑 hermes或者直接输入 hermes setup，会进入配置向导，这一步最容易踩坑。

先给你一张全景概览——设置向导大概会问 5 轮：

轮次	问什么	关键决策
第 1 轮	选安装模式	Quick / Full / Blank
第 2 轮	配 provider + API key	选哪家
第 3 轮	配命令执行后端	Local / Docker
第 4 轮	配消息网关	要不要接微信
第 5 轮	选默认模型 + 核心开关	开哪些功能

“
“
任何一步按 Ctrl+C 退出重来，已填内容不会丢。

第 1 轮：三选一

执行 `hermes` 命令输出如下选项：

每个选项的含义如下：

选项	说明	适合谁
Quick Setup（Nous Portal）	OAuth 登录，不用自备 key，用官方内置模型	新手，想马上体验
Full Setup	逐项手动配，自带 key	已有 key、想控成本
Blank Slate	几乎全关，后续手动开	清楚自己要什么的极客

我的建议：有 key 选 Full Setup，没 key 选 Quick Setup（前提是有账号）。新手千万别选 Blank Slate——漏配一个开关，后面就"莫名失灵"。

第 2 轮：配 API key

主流 provider 全支持。按网络环境给个推荐：

网络环境	推荐
海外	OpenAI / Anthropic 原生 API
国内直连	DeepSeek / MiniMax / OpenRouter（中转）
多模型切换	OpenRouter（一个 key 通吃多家）

预算为零也能跑，三条路：

OpenRouter 免费模型：注册即用，模型名带 :free 后缀的随便挑
商汤日日新 Token Plan：4 个模型公测免费（我写过详细教程，有兴趣的可以参考这个大厂免费给我 4 个 AI 模型，其中一个还能直接生成信息图？）
本地模型：装 Ollama 或者 LLM 跑本地模型，完全免费不吃额度（有条件的可参考Token自由！M1 Max 64G 本地部署 Gemma 4 26B，速度起飞！）

第 3 轮：命令执行后端

选项	说明
Local（默认）	命令直接跑你电脑上，最快最直接
Docker	容器隔离，防 Agent 误操作伤系统

新手保持 Local，完全正确。

第 4 轮：消息网关

向导支持 Telegram、Discord、Slack、飞书、微信等平台。

配好之后直接在聊天软件里给 Hermes 发任务，不用开终端。这也是 Hermes 和普通 Agent 工具最直观的体验差异。

“
“
接微信的话，私聊授权建议选**"配对审批"**——陌生人首次私聊需要你批准才能用，防止别人白嫖你的模型额度。

第 5 轮：两个核心开关

向导最后会问默认模型和核心开关，两个建议保持开启：

持久记忆：跨会话记住你的偏好，越用越懂你
技能生成：任务经验自动沉淀为可复用技能

这两个是 Hermes 区别于"一次性对话工具"的根基，关了等于把马养成金鱼。

直接改配置文件（适合不想跑向导的技术党）

不想跑向导，可以直接改 ~/.hermes/config.yaml：

四个新手最容易搞混的点：

字段	作用	新手常犯错误
`provider`	告诉 Hermes 用哪个 provider	填成模型名
`base_url`	API 地址	漏掉 `/v1`，报 404
`api_key`	你的密钥	格式不对，报 401
`custom_providers`	自定义 provider 列表	漏配，自定义模型不可用

注意 API key 存在 ~/.hermes/.env 里，可别截图到处乱传哦。

最后，跑一次测试

能收到回复 = 配置通了，终于，你跟 Hermes 对上话了。

报错对照（上一篇文章有个小伙伴关心的问题，我贴出来啦，记得看哦）：

错误码	原因	解决
404	base_url 填错	检查末尾有没有 `/v1`
401	API key 不对	重新复制
429	被限流	换个模型或等一会
Timeout	网络问题	换个 provider

验收标准：怎么算装好了

四条全满足 = 毕业：

✅ hermes --version 输出版本号

✅ hermes doctor 体检全绿，个别三角叹号无视

✅ 首启向导走完无报错

✅ 配了网关的话：在微信发一条消息，Hermes 回你了

最容易踩的三个坑

刚开始我装了三次才走通，卡了三次。下面这三个坑，大概率你也会遇到。基本上都是网络问题。

坑 1：Homebrew auto-update 卡死

第一次跑，脚本在装 ripgrep 和 ffmpeg 停了 5 分 40 秒，彻底不动。

原因：brew install 默认会先跑 brew update，macOS 上这一步经常卡住，原因不外乎就是网络。

解决1：加环境变量跳过

HOMEBREW_NO_AUTO_UPDATE=1 HOMEBREW_NO_ENV_HINTS=1 \curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

解决2: 修改HomeBrew镜像源

打开你的终端配置文件（通常是~/.zshrc），在文件末尾添加以下内容：

export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"

修改完，别忘了执行 source ~/.zshrc 一下。

后面再执行 brew install 或者 brew update 命令的时候就走国内镜像源啦。

坑 2：ffmpeg 下载卡死

第一次安装的时候由于网络原因一直卡着不动。

解决：要用严谨的态度上网

“
“
ffmpeg 不装也能跑 Hermes，只是语音消息功能不可用。急着想装通的，先跳过 ffmpeg。

坑 3：Playwright Chromium 下载

正常走通后会下载 162MB 的 Chromium。网络慢的时候也可能卡住。

解决：装的时候加 --skip-browser：

bash install.sh --non-interactive --skip-browser --skip-computer-use

非必须选项可以使用上面的方法跳过，必须用户，请科学的态度对待上网。

长期使用者必记

操作	命令	注意
更新	`hermes update`	会重启 gateway，有任务在跑别点
备份	拷贝整个 `~/.hermes` 目录	记忆和技能都在里面
卸载	删安装目录 + 数据目录	⚠️ 先备份再删，记忆会一并丢失

避坑速查表

症状	原因	解法
`curl 安装脚本超时`	GitHub 直连不稳	换 `res1.hermesagent.org.cn`
Windows `curl	bash` 报错	原生没 bash
PowerShell "禁止运行脚本"	执行策略限制	`Set-ExecutionPolicy -Scope Process Bypass`
装完 `hermes` 找不到	PATH 未生效	关掉重开 PowerShell
API 调用 401	Key 无效	重新复制
API 调用超时	网络问题	国内换 DeepSeek / OpenRouter
WSL2 内存被吃满	WSL2 默认无上限	新建 `.wslconfig` 限制内存

常用命令速查

命令	干什么
`hermes`	开始聊天（首次运行 = 进配置向导）
`hermes --continue`	接着上次会话继续
`hermes chat -q "问题"`	单次提问，不进界面
`hermes setup`	重跑配置向导
`hermes model`	换模型 / 换 provider
`hermes tools`	开关工具集
`hermes gateway`	启动消息网关
`hermes doctor`	体检：配置 / 网络 / 依赖
`hermes update`	升级最新版
`hermes migrate`	从 OpenClaw 一键搬家