【P1】第1期：Windows 用户必看！HermesAgent 安装全流程（无死角版）

本文由视频教程转写整理，重点梳理了在 Windows 系统上安装与使用 HermesAgent 的完整流程。网上多数教程讲的是 Linux 下安装，本教程专门针对习惯使用图形界面的 Windows 用户（尤其是非程序员）。

写作日期：2026-06-09｜复核：2026-09-07（隔三个月）

📌 2026-09-07 复核结论：主线流程仍然可照做，三处已漂移（全部已在正文改掉）

本文的说法复核结果

一键脚本 raw.githubusercontent.com/.../scripts/install.sh ✅ 仍在，且与官方现在推荐的短链字节完全相同

WSL2 + Ubuntu 路线、换源、前置条件 ✅ 未变（wsl 那几条是微软的命令）

hermes setup / hermes model / hermes gateway setup / setup --portal ✅ 四条都仍在官方文档与 README 里

脚本装的依赖含 Python 3.11 / uv / ripgrep / ffmpeg ✅ 仍对

脚本装 Node.js 22 🚨 已改成 26（install.sh 里 NODE_VERSION="26"）

「方式二：pip 安装（跟踪已发布的稳定版本）」 🚨 这条途径官方已弃用，见下方第四节的警告框

hermes postinstall 🚨 已不存在（README、install.sh、官方文档三处均查无此命令）

⭐ 这三处都是光看版本号发现不了的：项目版本从 0.19.0 改成了日期号 v2026.8.31，版本号变了本身说明不了哪条结论坏了。

🔔 别靠「感觉过了挺久」判断要不要重验，跑这四条（零成本、不需要装任何东西）：
# ① 一键脚本还在不在（本文基线：与官方短链字节相同）
curl -fsSL -o /tmp/a.sh https://hermes-agent.nousresearch.com/install.sh
curl -fsSL -o /tmp/b.sh https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh
cmp /tmp/a.sh /tmp/b.sh && echo "两条命令仍等价"

# ② 脚本钉的 Node / Python 版本（本文基线：NODE=26、PYTHON=3.11）
grep -oE '(NODE|PYTHON)_VERSION="[0-9.]+' /tmp/a.sh | sort -u

# ③ 正文用到的子命令是否还在官方文档里（本文基线：四条全在）
curl -fsSL https://hermes-agent.nousresearch.com/docs/getting-started/installation \
  | grep -oE 'hermes (setup|model|gateway|postinstall)' | sort -u

# ④ pip 那条途径是否复活（本文基线：PyPI 停在 0.19.0 / 2026-07-20）
curl -fsSL https://pypi.org/pypi/hermes-agent/json | grep -oE '"version":"[^"]+"' | head -1
⭐ 第 ②③ 条比版本号有用：它们直接检查本文引用的那几个事实。第 ③ 条若输出里出现 postinstall，说明那个命令回来了；若某条子命令消失，就是正文对应位置该改了。

本文的说法	复核结果
一键脚本 `raw.githubusercontent.com/.../scripts/install.sh`	✅ 仍在，且与官方现在推荐的短链字节完全相同
WSL2 + Ubuntu 路线、换源、前置条件	✅ 未变（`wsl` 那几条是微软的命令）
`hermes setup` / `hermes model` / `hermes gateway setup` / `setup --portal`	✅ 四条都仍在官方文档与 README 里
脚本装的依赖含 Python 3.11 / uv / ripgrep / ffmpeg	✅ 仍对
脚本装 Node.js 22	🚨 已改成 26（`install.sh` 里 `NODE_VERSION="26"`）
「方式二：pip 安装（跟踪已发布的稳定版本）」	🚨 这条途径官方已弃用，见下方第四节的警告框
`hermes postinstall`	🚨 已不存在（README、`install.sh`、官方文档三处均查无此命令）

一、整体流程概览

在 Windows 上安装 HermesAgent，本质是先搭好一个 Linux 运行环境，再在其中安装 Hermes。整个过程分为以下几大步骤：

安装 WSL 2（第二版本的 Windows Subsystem for Linux）
安装 Ubuntu（一个 Linux 系统）
准备工作（换源等，让国内下载更快、安装依赖工具）
安装与使用 HermesAgent
配置通讯工具（如飞书，类似 ClaudeCode 的接入方式）
退出后如何再次启动使用

关键认知：本教程采用 WSL2 + Ubuntu 路线——先在 Windows 上虚拟出一个 Linux 环境，再在其中安装 Hermes。视频里前面大量工作本质都是“环境搭建”。如果你是 Linux 或 macOS 用户，可跳过 WSL/Ubuntu 部分，直接看第四节起的安装命令。

📌 补充（官方文档说明）：HermesAgent 官方现已支持原生 Windows安装（CLI、网关、TUI、工具均可原生运行），不一定非要装 WSL2。但视频演示与本教程走的是更通用、报错更少的 WSL2 路线；若你想尝试原生 Windows 安装，可参考官方 Windows (Native) Guide。两种方式可以共存。

〇、安装前置条件（视频未提，但很关键）

真实安装中最常见的失败都发生在环境没准备好。开始前请确认：

Windows 版本：Windows 11，或 Windows 10 版本 2004 及以上（内部版本 19041+）。低于此版本无法使用 wsl --install 一键安装。
CPU 虚拟化已开启：WSL2 依赖虚拟化。若 wsl --install 报错，多半是 BIOS/UEFI 里的虚拟化（Intel 为 VT-x，AMD 为 SVM / AMD-V）被关闭，需进 BIOS 打开。可在「任务管理器 → 性能 → CPU」查看“虚拟化：已启用”。
磁盘空间：建议预留至少 10–15 GB（Ubuntu 系统 + Hermes 及其依赖、模型缓存）。
内存：建议 8 GB 及以上。
网络：能正常访问网络；国内用户务必按步骤 4 换源，否则下载会非常慢。

预计总耗时：约 30 分钟 ~ 1 小时。其中绝大部分时间花在第四节 Hermes 安装的某个依赖编译/下载步骤上（视频作者等了约半小时，与网络强相关），其余步骤都很快。

二、先看最终效果（安装完成后怎么用）

安装完成后有两种使用方式：

方式一：命令行直接使用

在 Windows「开始菜单」里找到 Ubuntu，打开进入命令行。
输入 hermes 启动，启动后即可与 HermesAgent 交流。
演示中连接的是 DeepSeek 推理模型，让它做自我介绍——它会介绍自身特点：持久记忆、技能系统、多工具集成、运行在 WSL 中。
与 ClaudeCode 不同，Hermes 命令行使用时没有图形界面，就是纯命令行交互。
退出命令：Ctrl + C，退出后回到命令行输入状态。

方式二：在通讯工具中使用（如飞书）

和 ClaudeCode（及其衍生工具）一样，Hermes 装好后可以接入飞书、微信等通讯工具。
启动后无需管它，回到飞书与配置好的机器人对话即可。
机器人收到消息会有“正在处理”提示，随后给出回答。

三、详细安装步骤

步骤 1：安装 WSL 2

用管理员身份打开命令行：Windows + X → 选择「终端管理员」（或任何你熟悉的方式，但必须是管理员身份）。
输入安装命令：
```
wsl --install
```
稍等片刻即可安装完成，过程中会有相应提示，最后进入另一个命令行界面。

注意：有的教程说这一步会自动安装 Ubuntu，但本教程实测并未自动安装——没关系，没装的话后面手动安装即可，这一步很快。

安装完成后需要重启电脑。

步骤 2：重启后检查 WSL 状态

重启完成后，再次用管理员身份打开命令行，确认 WSL 状态：

wsl --status

要确认的关键点：默认版本是 2（官方要求 WSL 2 环境，才能让 Ubuntu 很好地运行）。
若显示的默认版本不是 2，执行下面命令改为 2：
```
wsl --set-default-version 2
```

查看可用的在线发行版（可选检查）：

wsl --list --online

步骤 3：安装 Ubuntu

确认状态无误后，安装指定版本的 Ubuntu（推荐用列表里的常用 LTS 版本）。例如安装 Ubuntu 24.04：

wsl --install -d Ubuntu-24.04

也可直接用 wsl --install -d Ubuntu 安装默认 Ubuntu。具体可选名称以 wsl --list --online 输出为准。

过程中可能弹出一个 WSL 图形界面窗口，不用管，直接关掉。因为全程都是用命令行配置，不需要图形界面。

设置 Ubuntu 用户名和密码（重点！）：

安装过程类似你自己的 Windows 电脑，需要设置一个用户名和一个开机密码。
⚠️ 用户名必须全部小写，有大写会报错（教程中作者取名 andy，之前用别的带大写的名字就报错了）。
输入密码时屏幕不显示任何字符，这是正常现象，不要以为输入法出错。输入完回车，再确认一遍密码回车即可。
⚠️ 用户名和密码一定要记住，因为后续在 Ubuntu 上做很多操作都需要输入密码。

步骤 4：配置 Ubuntu（换国内镜像源）

为什么要换源：不换源默认连 Ubuntu 国外官方服务器（archive.ubuntu.com），国内访问慢且常超时；换成**国内镜像源（如阿里云源）**后下载安装会快很多。

⚠️ 注意 Ubuntu 版本差异：Ubuntu 24.04 起改用新的 deb822 格式，源文件路径是 /etc/apt/sources.list.d/ubuntu.sources；22.04 及更早仍是 /etc/apt/sources.list。两者命令不同，按你装的版本选用。

Ubuntu 24.04（及更新版本）换阿里云源：

# 1) 先备份
sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak

# 2) 把官方地址替换为阿里云镜像
sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g; s@//security.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list.d/ubuntu.sources

Ubuntu 22.04 / 20.04 换阿里云源：

sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo sed -i 's@//.*archive.ubuntu.com@//mirrors.aliyun.com@g; s@//security.ubuntu.com@//mirrors.aliyun.com@g' /etc/apt/sources.list

执行时如提示输入密码，就输入步骤 3 设置的那个密码（输入不显示是正常的）。
换源后刷新软件包索引（这就是视频里说的“更新操作”）：

sudo apt update

完成后回到命令行输入状态，Ubuntu 这部分就配置好了。

想确认换源成功，可执行 cat /etc/apt/sources.list.d/ubuntu.sources（或 .../sources.list），看 URL 是否已变成 mirrors.aliyun.com。需要还原时，用前面备份的 .bak 文件覆盖回去即可。

步骤 5：安装依赖工具（准备工作）

Hermes 运行需要一些底层工具支撑。视频里提到“装 4 个工具”，对应 HermesAgent 官方安装脚本会自动准备的依赖，主要是：

Git（唯一需要你手动确保的前置工具，安装脚本会用它克隆代码）
uv（Python 包/环境管理器，安装脚本会自动装，并据此自动准备 Python 3.11，你无需手动装 Python）
Node.js（部分工具/浏览器能力依赖。写作时脚本钉 22，2026-09-07 复核已是 26 —— 这个数字会继续变，别记它，跑顶部第 ② 条判据看当天的值）
ripgrep、ffmpeg（搜索与音视频处理）

实际上，uv、Node.js、ripgrep、ffmpeg 这些大多由第四节的官方安装脚本自动安装，你通常只需先确保 Git 可用。手动安装 Git（及常见编译依赖）可执行：

sudo apt install -y git curl build-essential

其中某个组件的下载/编译可能比较慢，看起来像卡住，其实是正常的，耐心等待即可；其余步骤都很快。

四、安装 HermesAgent

准备工作做好后，回到 Ubuntu 命令行，执行 HermesAgent 官方安装命令。官方提供两种方式：

方式一：一键脚本安装（跟踪最新 main 分支，推荐 / 视频所用方式）

# 官方现在文档里给的是这条短链
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 视频里用的是仓库原始地址，2026-09-07 实测两者字节完全相同
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

该脚本会自动安装 uv、Python 3.11、Node.js 26、ripgrep、ffmpeg 等依赖（前提是已有 Git），并生成可用的 hermes 命令。在干净的 Ubuntu 上脚本本身约 90 秒跑完，但其中依赖的下载/编译耗时与网络强相关。

⚠️ 写作时这里是 Node.js 22，2026-09-07 复核已改成 26（脚本里的 NODE_VERSION="26"）。版本号会继续往前走，跑一下顶部第 ② 条判据就能拿到当天的真值。

方式二：pip 安装 —— 🚨 官方已弃用，不要再用

# ⛔ 这两条 2026-06 写作时有效，2026-09-07 复核已不推荐
pip install hermes-agent
hermes postinstall

🚨 2026-09-07 复核：这条途径已经废了，三个独立证据

PyPI 停更：最后一次发布是 0.19.0（2026-07-20），而仓库 main 天天在动。也就是说 pip install 装到的是一个七周前的快照，不是“已发布的稳定版本”。

官方不再提它：README 和官方安装文档里 pip install 各出现 0 次，全部改走 install.sh + uv。

版本方案换了：GitHub Releases 已改用日期号（最新 v2026.8.31），与 PyPI 上的语义版本 0.19.0 不是一套体系，对不上。

另外 hermes postinstall 这个命令也已经不存在了 —— README、install.sh、官方文档三处都查无此命令。装完之后要初始化，走下一节的 hermes setup。

⇒ 现在只用方式一。 保留这一段是为了让照着老教程走的人知道自己卡在哪儿，而不是删掉它假装从来没推荐过。

安全提示：以上为官方仓库（NousResearch/hermes-agent）地址。用管道执行网络脚本前，建议先把链接在浏览器打开看一眼内容，确认无误再运行。

安装过程注意事项：

中间会有一些提醒，看不懂就直接问 AI（作者一开始也不懂，问一下就明白了）。
遇到询问 yes / no 时，输入 Y 回车继续。
⚠️ 执行到某个依赖编译/安装步骤会非常慢（视频里听起来像 good tool install，实为某依赖的编译安装环节），作者等了大约半小时。只要不是红色报错文字，就耐心等待、不要中断。
速度与网络环境强相关：它本身有下载、解析、编译、安装的完整过程。

五、配置大模型

安装好后进入大模型配置环节。可运行配置向导：

hermes setup        # 交互式初始化向导
# 或之后单独切换模型：
hermes model        # 交互式选择默认 provider 与模型

本教程版本直接进入配置，没有像别的教程那样让你选「快速安装 / 详细安装」（官方在持续优化安装流程；全新安装也可用 hermes setup --portal 一次性登录并用 Nous 作为 provider）。
选择你自己拥有 token 的大模型即可。使用这类 Agent 工具需要自己支付 token 费用——你买了哪个大模型的 token 就选哪个。Hermes 与模型无关，支持 DeepSeek、OpenAI、Anthropic、OpenRouter 以及本地模型等。
作者用的是 DeepSeek。
如果列表里没有你要用的模型，就选「自定义 / Custom」选项，然后根据提示填入 API Key 和 Base URL。
- 不管用哪个模型，API Key 一定要填，Base URL 基本也要填。
- DeepSeek 的 Base URL 为 https://api.deepseek.com（模型名按 DeepSeek 官方当前提供的为准）。
- 不知道某模型的 Base URL，可上网搜或直接问对应大模型“你的 API Base URL 是什么”，按提示填上。

🔐 安全提示：API Key 等同于你的付费凭证，不要泄露、不要截图分享、不要提交到代码仓库。粘贴时终端默认不回显属正常。

配置好模型后，命令行使用基本就没问题了。接下来若出现可选项（如配置网关/技能等），可先选「跳过（Skip）」，先把基础对话跑通再说。

六、首次试用（命令行）

跳过后查看命令行状态，如果还在执行任务，用 Ctrl + C 停止，回到命令行输入状态。
执行启动命令：
```
hermes
```
启动后即为 HermesAgent 交互界面（即开头演示的样子），可以跟它交流、让它做自我介绍，先熟悉一下。

至此，基础安装已完成。

七、配置通讯工具（以飞书为例）

Hermes 可接入微信、飞书、企业微信、钉钉等多种通讯工具。作者偏爱飞书，原因：

飞书文档协作、交流办公比较方便；
与微信不同，飞书可以接入多个机器人。

步骤 1：一键创建飞书机器人

在工具中找到「一键创建飞书机器人」，把链接复制到浏览器打开。
修改助手名称、选择头像，点「创建」即可（创建很快，约 10 秒）。
创建完成后会得到 App ID 和 App Secret。

概念说明：在飞书创建的机器人是以「应用」形式呈现的。机器人要和你的 HermesAgent 交互，需要一套身份与密码机制——App ID 就是身份，App Secret 就是密码。把这两者交给 HermesAgent，二者就能连接起来。

步骤 2：在 Hermes 中连接飞书机器人

回到命令行，先 Ctrl + C 停掉试用状态。
运行网关配置向导：
```
hermes gateway setup
```
用键盘上下键在平台列表里选择「飞书 / Feishu / Lark」，回车。
选择连接 / 鉴权模式：选中使用 App ID + App Secret 的方式，回车。
依次填入 App ID 和 App Secret（粘贴时同样不显示，粘一遍回车即可）。
选择飞书版本：选「国内版（Feishu）」（第一个），回车；海外 Lark 选国际版。
配置连接方式 WebSocket：选「第一个（长连接模式）」——由 Hermes 主动连接飞书服务器，不需要公网 IP。
配置验证方式：选「第一个（配对码形式）」。因为仅有 App ID + App Secret 还不够安全，需配对码机制完成验证。

说明：在飞书开发者后台需为该应用开启「机器人」能力，它才能收发消息；App ID / App Secret 在应用的「凭证与基础信息」里获取。

步骤 3：获取配对码并完成连接

创建好飞书机器人后，机器人那端会有消息提醒。打开该应用进入对话框，随便发一句话。
由于是配对机制，第一次发消息后机器人会回复一个配对码（用你自己的配对码，不要抄教程里的）。
回到命令行，用以下命令启动网关：
```
hermes gateway
```
启动后它会提示飞书连接是否成功之类信息。把它给出的对应命令复制过去执行，完成配对码验证。
执行完出现成功提示即配置完成。

八、两种使用方式总结

核心第一步永远是：打开命令行。 注意——打开的不是 Windows 命令行，而是你安装的 Linux（Ubuntu）命令行，从开始菜单里找到 Ubuntu 打开即可。

使用场景	启动命令	界面
命令行中直接使用	`hermes`	命令行窗口交互
在飞书等通讯工具中使用	`hermes gateway`	在飞书里与机器人交互

两者本质相同，都是命令行启动，区别只在于：

要在飞书里用 → 加 gateway（hermes gateway）；
不在飞书里用 → 不加 gateway（直接 hermes）。

按自己需求选择即可。

九、作者使用感受与补充

安装难度：如果你装过 ClaudeCode，再装 Hermes 会觉得相对简单，基本不会出现不可控的问题。

Hermes 的进化点（相比 ClaudeCode）：

在 Agent 中与它一起完成一项工作后，它会很自主地把你的工作沉淀成 Skill（技能）。
而 ClaudeCode 通常需要你做完后主动跟它说，再一起总结成 Skill，它才会去做。这一点 Hermes 更高级。

关于 CLI（命令行界面）的补充说明：

网上最近很火地强调 CLI，却没说清楚原因。一句话解释：GUI（图形界面）是给人用的。
程序员需要学通命令行语法才能用好 CLI，对外行像看天书、比较痛苦；但 AI 识别命令行非常高效。
AI 识别 GUI（通讯界面、各种按钮设计）需要依赖 OCR、多模态等能力，依然比较耗时。
因此现在大厂很多都在推 CLI，并称其为「AI 的终极归宿」。了解它的用途，不要排斥它。

下一期：作者计划分享 HermesAgent 更进阶的使用技巧。

十、常见问题与排查（视频未涵盖）

wsl --install 报错 / 卡住：多为 CPU 虚拟化未开启。进 BIOS/UEFI 打开 VT-x（Intel）或 SVM（AMD），并确认 Windows 已启用「虚拟机平台」和「适用于 Linux 的 Windows 子系统」功能（可在「启用或关闭 Windows 功能」中勾选）。
wsl --status 默认版本不是 2：执行 wsl --set-default-version 2，必要时对已装发行版执行 wsl --set-version <发行版名> 2。
创建 Ubuntu 用户名报错：用户名必须全小写、不含空格和特殊字符。
忘记 Ubuntu 密码：可用管理员命令行执行 wsl -u root 进入，再用 passwd 你的用户名 重设。
apt update 仍很慢或报错：确认换源命令改对了文件（24.04 是 ubuntu.sources），并检查 URL 是否拼写正确；可改用清华 mirrors.tuna.tsinghua.edu.cn 等其他国内源。
Hermes 安装中途“卡住”：只要不是红色 error，多是依赖编译/下载慢，耐心等待；可另开终端用 top 看是否仍在占用 CPU/网络。
hermes 命令找不到（command not found）：重开一个终端让 PATH 生效；或确认安装脚本已成功结束。
飞书机器人不回消息：确认应用已开启机器人能力、网关 hermes gateway 正在运行、且配对码验证已成功。

附：常用命令速查

用途	命令
安装 WSL	`wsl --install`
查看 WSL 状态（确认默认版本为 2）	`wsl --status`
设置默认版本为 2	`wsl --set-default-version 2`
查看可用在线发行版	`wsl --list --online`
安装指定发行版	`wsl --install -d Ubuntu-24.04`
一键安装 Hermes（官方短链，推荐）	`curl -fsSL https://hermes-agent.nousresearch.com/install.sh \| bash`
一键安装 Hermes（仓库地址，等价）	`curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh \| bash`
~~pip 安装 Hermes~~	🚨 官方已弃用，PyPI 停在 `0.19.0`（2026-07-20），见第四节
初始化 / 配置向导	`hermes setup`
切换默认模型	`hermes model`
配置通讯网关（如飞书）	`hermes gateway setup`
启动 Hermes（命令行模式）	`hermes`
启动 Hermes 网关（飞书等通讯工具模式）	`hermes gateway`
退出 / 停止	`Ctrl + C`

说明：本文命令已对照 HermesAgent 官方文档核实（视频口播中的 hermes set、good tool install 等为语音转写近似，已据官方修正为 hermes setup / hermes gateway setup 等）。Hermes 仍在快速迭代，实际命令与交互选项请以你安装版本的提示及官方文档为准。