Windows 用户必看：WSL2 安装 Hermes Agent 完整教程（新手友好）

Hermes
-
- 字
2026-05-12

Windows 用户必看：WSL2 安装 Hermes Agent 完整教程（新手友好）※

很多 Windows 老板想体验 Hermes Agent，但看到「Linux 命令」就发懵——别怕，这篇教程手把手带你从零安装。

我们选择的是官方推荐的 WSL2 方案，也是踩坑最少、最接近官方文档体验的一条路。整个过程其实就三步，看完你就会了。

一、前置认知：什么是 WSL2？为什么要选它？※

WSL2 的全名是 Windows Subsystem for Linux 2，翻译过来就是「Windows 上的 Linux 子系统第二代」。

你可以简单理解为：微软在 Windows 系统里给你塞了一个完整的 Linux 环境，不用装双系统，不用虚拟机，开机就能用。

装了 WSL2 之后，你平时怎么用？※

简单说：

  • 你的桌面还是 Windows，不影响任何习惯
  • 只在装 Hermes Agent 和运行它的时候，打开 Ubuntu（WSL2）这个终端
  • 以后看到文档里写 Linux/macOS 命令，就往这个 Ubuntu 终端里粘贴执行

为什么推荐 WSL2 而不是原生 PowerShell？※

Hermes Agent 的很多能力本来就是为类 Unix 环境设计的，比如：

  • Python / Node.js 依赖安装
  • 浏览器自动化
  • Docker、SSH、MCP 等扩展能力

在 WSL2 里，这些东西运行更稳定，遇到问题 Google 搜到的解决方案也更多。PowerShell 方案能用，但遇到兼容性问题时排查起来更费劲。

一句话：长期用、工具链完整 → 选 WSL2；就想先快速跑起来 → PowerShell。 既然老板你想认真用，那就从 WSL2 开始。

二、安装 WSL2（第一步）※

Step 1：打开管理员 PowerShell※

这是整个安装过程最关键的一步，操作错误会直接影响 WSL2 是否能正常安装。

操作步骤：

  1. 按键盘左下角的 Windows 键
  2. 输入 PowerShell
  3. 在搜索结果里右键「Windows PowerShell」
  4. 选择「以管理员身份运行」

⚠️ 注意：普通 PowerShell 窗口安装 WSL2 大概率会报错，必须是管理员权限！

Step 2：在管理员 PowerShell 里运行安装命令※

管理员 PowerShell 打开后，复制下面这条命令，粘贴进去，按回车：

wsl --install -d Ubuntu

怎么粘贴？

  • 最常用：Ctrl + V
  • 如果 Ctrl+V 没反应：在 PowerShell 窗口里点一下右键，很多电脑会自动粘贴

Step 3：等待下载完成并重启电脑※

命令执行后，会自动下载 Ubuntu 组件和镜像。界面会提示你：

Please restart your computer to complete the installation.

看到这条提示就说明前面的步骤都对了，保存好手头的工作，重启电脑。

Step 4：重启后设置 Ubuntu 用户名和密码※

电脑重启后，会自动弹出一个 Ubuntu 终端窗口（黑底绿字或白字）。首次使用需要你创建 Linux 用户账号：

  1. 提示 Enter new UNIX username: 时，输入一个英文字母用户名（比如 hermes），按回车
  2. 提示 New password: 时，输入密码（输入时屏幕不显示字符，正常现象），按回车
  3. 提示 Retype new password: 时，再输入一遍密码确认

💡 提示：Ubuntu 里的密码输入是"盲打"——你看不到任何字符（连 * 都没有），这是 Linux 的安全设计，别慌，坚定地输入完按回车就行。

验证 WSL2 是否安装成功※

设置完成后，你可以随时在 Windows 搜索框输入 Ubuntu 打开这个终端。

在 Ubuntu 终端里输入：

wsl --list --verbose

看到类似这样的输出就说明安装成功了：

NAME                   STATE           VERSION
* Ubuntu                Running         2

VERSION 后面显示的是 2，说明是 WSL2（如果是 1 就需要升级）。

三、安装 Hermes Agent（第二步）※

Step 1：打开 Ubuntu 终端※

确保进入的是 Ubuntu 终端（不是 PowerShell），窗口标题通常显示 Ubuntu。

Step 2：复制粘贴安装命令※

在 Ubuntu 终端里，复制下面这条命令：

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

在 Ubuntu 终端里粘贴并回车执行（Ubuntu 终端里 Ctrl+Shift+V 是标准粘贴快捷键，Ctrl+V 也通常支持）。

🌐 中国大陆用户注意：这条命令已经接入了国内镜像加速，优先走国内可直连的下载链路，比原版安装顺畅很多。

Step 3：等待安装完成※

安装过程会依次处理：

  • uv（Python 版本管理工具）
  • Python 3.x
  • Node.js
  • Git
  • Hermes Agent 本体及虚拟环境

安装时间取决于网络状况，通常 3-10 分钟不等。看到类似以下输出说明安装完成：

Hermes Agent installed successfully!

Step 4：激活 Hermes 命令※

安装脚本完成后，需要重新加载一下环境变量才能识别 hermes 命令。在终端里运行：

source ~/.bashrc

然后验证 Hermes 是否安装成功：

hermes

如果看到 Hermes 的 logo 和帮助信息，说明安装成功！

四、配置模型（第三步）※

Step 1：配置模型服务商※

在终端里运行：

hermes model

这会启动一个交互式配置向导，你需要选择和填写：

  • 使用哪个模型服务商（如 OpenAI、Claude、本地 Ollama 等）
  • API Key 或相关凭证
  • 默认模型选择

Step 2：完成基础设置※

hermes setup

按提示完成初始化配置。

Step 3：验证是否正常运行※

hermes

能正常启动并看到交互提示，说明整个安装流程全部完成！

五、接入飞书（第四步）※

恭喜老板走到这一步！前面三步搞定了 Hermes Agent 的本体和模型配置，现在来把它接入飞书，让你在飞书群里直接 @ 机器人对话。

5.1 创建飞书机器人应用※

第一步：打开 飞书开放平台，创建一个企业自建应用。

  1. 访问 https://open.feishu.cn/，用管理员账号登录
  2. 进入「开发者后台」→ 点击「创建企业自建应用」
  3. 填写应用名称（随意，比如「Hermes 助手」）和描述
  4. 创建完成后，在「凭证与基础信息」页面找到 App ID 和 App Secret，这两个后面要填到 Hermes 里

5.2 配置飞书应用权限※

飞书机器人需要申请多个权限才能正常工作。在应用后台依次开通：

  • 机器人能力（先开启这个，否则后面无法添加机器人）
  • im:message（读取和发送消息）
  • im:message.group_at_msg（接收群聊 @ 机器人消息）
  • im:message.send_as_bot（以机器人身份发送消息）
  • im:chat（读取群信息）

💡 开通路径：飞书开放平台 → 你的应用 → 「权限管理」→ 搜索对应权限名称 → 申请开通。通常即时生效，部分企业需要管理员审批。

5.3 配置事件订阅※

在飞书开放平台开启长连接模式，让 Hermes 能实时接收飞书消息：

  1. 进入应用 → 「事件与回调」→「事件订阅」
  2. 选择「长连接接收事件」（推荐，配置最简单）
  3. 添加事件：im.message.receive_v1（接收消息）
  4. 保存配置

5.4 在 Hermes 里配置飞书渠道※

回到 Ubuntu 终端，运行：

hermes gateway setup

在渠道列表中选择「飞书」，依次填入：

  • App ID：飞书开放平台复制过来的 App ID
  • App Secret：对应的 App Secret
  • 来源：国内版填 feishu，海外版填 lark
  • 连接方式：默认 websocket，直接回车即可
  • 允许的 User ID：留空；在鉴权步骤输入 1（不限制对话人），这样群里所有人都可以 @ 机器人对话

确认无误后选择 Done 保存。

5.5 启动飞书网关※

配置完成后，启动网关：

hermes gateway run -vv

看到类似「Feishu gateway started」或无报错输出，说明飞书接入成功！

5.6 在飞书群里添加机器人※

  1. 打开目标飞书群 → 右上角「设置」→「群机器人」
  2. 点击「添加机器人」
  3. 找到你刚创建的应用名称，点击添加
  4. 在群里 @机器人 发一条消息，如果机器人回复了，说明对接成功！

六、常见问题汇总※

Q1：wsl --install -d Ubuntu 报错「找不到命令」？※

原因：你可能在普通 PowerShell（而非管理员 PowerShell）里运行，或者 WSL 功能本身被系统禁用了。

解决方法：

  1. 确认是以管理员身份打开的 PowerShell
  2. 在管理员 PowerShell 里先运行：dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  3. 然后再运行：wsl --install -d Ubuntu

Q2：安装 WSL2 时卡在「正在下载」不动？※

原因：可能是网络问题或 WSL Ubuntu 镜像下载源在国内访问较慢。

解决方法：

  • 确保电脑已开启稳定网络
  • 可以尝试给 WSL 设置国内镜像，具体方法可以搜索「WSL 镜像源配置」
  • 耐心等待，下载时间可能较长（300MB-1GB+）

Q3：重启后 Ubuntu 窗口直接闪退？※

原因：WSL 安装过程异常或 WSL 服务没有正常启动。

解决方法：

  1. 以管理员身份打开 PowerShell
  2. 运行：wsl --shutdown（关闭所有 WSL）
  3. 再重新打开 Ubuntu 窗口

Q4：hermes 命令找不到（command not found）？※

原因：环境变量没有刷新，或者安装没有成功。

解决方法：

source ~/.bashrc

如果还不行，检查安装是否成功：

ls ~/.local/bin/hermes

如果目录不存在，说明安装失败，重新运行安装命令。

Q5：配置模型时提示网络错误？※

原因：如果你的模型服务商（如 Ollama、LM Studio）跑在 Windows 本机上，而 Hermes 跑在 WSL2 中，WSL2 访问 Windows localhost 的网络配置需要额外设置。

解决方法：参考官方文档里的 WSL2 网络配置说明，需要把 Windows 主机的 IP 配置到 WSL2 的网络里。

Q6：Ubuntu 终端里复制粘贴快捷键是什么？※

标准快捷键：

  • 粘贴：Ctrl + Shift + V（Ubuntu 终端标准）
  • 复制：选中文字后，Ctrl + Shift + C
  • 很多终端也支持 Ctrl + V 直接粘贴，可以先试试

Q7：运行 hermes gateway 报 lark-oapi 未安装？※

原因：WSL2 下飞书 SDK 有时没装进 Hermes 的虚拟环境。

解决方法：

uv pip install lark-oapi

如果报错提示权限问题，尝试：

uv pip install lark-oapi --system

Q8：飞书群里 @ 机器人没有响应？※

排查顺序：

  1. 检查飞书机器人权限是否全部申请通过（参考 5.2 节权限清单）
  2. 确认 Hermes Gateway 是否正常运行，无报错日志
  3. 确认飞书应用已添加进目标群
  4. 确认飞书开放平台的「事件订阅」已开启长连接模式

Q9：飞书提示"机器人已禁用"？※

原因：飞书应用没有发布，或者企业管理员限制了机器人使用。

解决方法：

  1. 在飞书开放平台 → 应用 → 「版本管理与发布」→ 创建版本并提交发布
  2. 如果是企业管理员账号，检查「机器人」功能是否对企业内所有成员开放

七、安装完成后的正确使用姿势※

以后你用 Hermes Agent 的流程是这样的：

  1. 打开 Windows 搜索框 → 输入「Ubuntu」→ 打开 WSL2 终端
  2. 在 Ubuntu 终端里运行各种 hermes 命令
  3. 平时该用 Windows 继续用 Windows，Hermes 不影响你任何工作

以后看到文档里写这类命令：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash
hermes model
hermes gateway run -vv

记住：这类 Linux/macOS 命令都要在 WSL2 的 Ubuntu 终端里执行，不要粘贴到 PowerShell！

八、总结※

整个 WSL2 安装 Hermes Agent 并接入飞书的流程，用一张图总结就是：


graph TD
    A[以管理员身份打开 PowerShell] --> B[运行 wsl --install -d Ubuntu]
    B --> C[重启电脑]
    C --> D[设置 Ubuntu 用户名和密码]
    D --> E[打开 Ubuntu 终端]
    E --> F[运行安装命令]
    F --> G[source ~/.bashrc]
    G --> H[运行 hermes model 配置模型]
    H --> I[hermes gateway setup 配置飞书]
    I --> J[hermes gateway run -vv 启动]
    J --> K[✅ 完成！在飞书群里 @ 机器人对话]

老板，恭喜你完成了 Windows 上 Hermes Agent 的完整安装和飞书接入！WSL2 这条路虽然多装了一步，但后续使用起来稳定很多，遇到问题也更容易找到解决方案。

飞书接入完成后，你和团队成员就可以直接在飞书群里 @Hermes 机器人，随时调用 AI 能力，效率拉满 🚀

参考资料：Hermes Agent 中文社区 - Windows 安装文档｜阿里云 - Windows 也能跑 Hermes Agent！完整安装教程 + 飞书接入

“您的支持是我持续分享的动力”

微信收款码
微信
支付宝收款码
支付宝
目录