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

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

一、整体流程概览

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

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

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

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

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

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

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

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

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

方式一：命令行直接使用

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

三、详细安装步骤

步骤 1：安装 WSL 2

  1. 用管理员身份打开命令行：Windows + X → 选择「终端管理员」（或任何你熟悉的方式，但必须是管理员身份）。

  2. 输入安装命令：

    wsl --install

  3. 稍等片刻即可安装完成，过程中会有相应提示，最后进入另一个命令行界面。

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

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

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

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

wsl --status

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

wsl --list --online

步骤 3：安装 Ubuntu

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

wsl --install -d Ubuntu-24.04

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

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

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

⚠️ 注意 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
sudo apt update

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

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

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

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

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

sudo apt install -y git curl build-essential

四、安装 HermesAgent

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

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

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

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

方式二：pip 安装（跟踪已发布的稳定版本）

pip install hermes-agent
hermes postinstall   # 可选：安装 Node.js、浏览器、ripgrep、ffmpeg 并完成初始化

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

安装过程注意事项：

五、配置大模型

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

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

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

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

六、首次试用（命令行）

  1. 跳过后查看命令行状态，如果还在执行任务，用 Ctrl + C 停止，回到命令行输入状态。

  2. 执行启动命令：

    hermes

  3. 启动后即为 HermesAgent 交互界面（即开头演示的样子），可以跟它交流、让它做自我介绍，先熟悉一下。

至此，基础安装已完成。

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

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

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

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

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

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

  1. 回到命令行，先 Ctrl + C 停掉试用状态。

  2. 运行网关配置向导：

    hermes gateway setup

  3. 用键盘上下键在平台列表里选择「飞书 / Feishu / Lark」，回车。

  4. 选择连接 / 鉴权模式：选中使用 App ID + App Secret 的方式，回车。

  5. 依次填入 App ID 和 App Secret（粘贴时同样不显示，粘一遍回车即可）。

  6. 选择飞书版本：选「国内版（Feishu）」（第一个），回车；海外 Lark 选国际版。

  7. 配置连接方式 WebSocket：选「第一个（长连接模式）」——由 Hermes 主动连接飞书服务器，不需要公网 IP。

  8. 配置验证方式：选「第一个（配对码形式）」。因为仅有 App ID + App Secret 还不够安全，需配对码机制完成验证。

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

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

  1. 创建好飞书机器人后，机器人那端会有消息提醒。打开该应用进入对话框，随便发一句话。

  2. 由于是配对机制，第一次发消息后机器人会回复一个配对码（用你自己的配对码，不要抄教程里的）。

  3. 回到命令行，用以下命令启动网关：

    hermes gateway

  4. 启动后它会提示飞书连接是否成功之类信息。把它给出的对应命令复制过去执行，完成配对码验证。

  5. 执行完出现成功提示即配置完成。

八、两种使用方式总结

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

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

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

按自己需求选择即可。

九、作者使用感受与补充

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

Hermes 的进化点（相比 ClaudeCode）：

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

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

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

附：常用命令速查

用途 命令
安装 WSL wsl --install
查看 WSL 状态（确认默认版本为 2） wsl --status
设置默认版本为 2 wsl --set-default-version 2
查看可用在线发行版 wsl --list --online
安装指定发行版 wsl --install -d Ubuntu-24.04
一键安装 Hermes（main 分支） curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
pip 安装 Hermes（稳定版） pip install hermes-agent
初始化 / 配置向导 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 仍在快速迭代，实际命令与交互选项请以你安装版本的提示及官方文档为准。

参考来源（官方文档）

← 返回 AI 编程