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

Hermes
-
- 字
2026-05-13

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-LLinux /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！

八、多智能体配置： Hermes Agent 的真实协作能力※

恭喜老板走完基础安装！当你的任务越来越复杂时，单一 Agent 的能力会逐渐遇到瓶颈——这时候，Hermes 内置的多智能体工具就能派上用场了。

很多老板容易把 Hermes 和 OpenClaw 的多智能体系统搞混——它们是两套完全不同的机制。Hermes 有自己原生的多智能体工具：delegate_task（子 Agent 委派）和 mixture_of_agents（多模型协同）。本节详细介绍这两个工具的真实用法。

8.1 子 Agent 委派：delegate_task※

delegate_task 是 Hermes 内置的子 Agent 委派工具，属于 delegation 工具集。它的核心能力是：

  • 在隔离上下文中启动一个或多个子 Agent 处理独立任务
  • 每个子 Agent 拥有独立的对话、终端会话和工具集
  • 子 Agent 的中间结果不会污染主 Agent 的上下文窗口，只返回最终摘要
  • 支持并行派发多个子 Agent，同时处理不同子任务

这意味着什么？举个例子：你要做一个市场调研分析，主 Agent 可以同时派发三个子 Agent——一个搜竞品数据，一个查行业报告，一个整理用户反馈——三者并行工作，主 Agent 最后汇总三份摘要输出完整分析，效率提升数倍。

delegate_task 参数说明※

参数说明
task给子 Agent 的任务描述（支持复杂指令）
model可选，指定子 Agent 使用的模型，不填则用主 Agent 的模型
tools子 Agent 可用的工具集，默认继承主 Agent 工具
background是否后台运行，true=后台并行，false=等待完成

使用示例：并行代码审查※

假设你需要同时审查三个模块的代码质量：

// 主 Agent 并行派发三个代码审查子 Agent
delegate_task(
  task="请审查 ~/hermes-workspace/src/auth.py 的代码质量，重点检查：1)安全性漏洞 2)错误处理 3)代码规范。输出结构化审查报告。",
  model="claude-sonnet-4-20250514",
  tools=["read_file", "search_files", "terminal"],
  background=true
)

delegate_task(
  task="请审查 ~/hermes-workspace/src/api.py 的代码质量，重点检查：1)安全性漏洞 2)错误处理 3)代码规范。输出结构化审查报告。",
  model="claude-sonnet-4-20250514",
  tools=["read_file", "search_files", "terminal"],
  background=true
)

delegate_task(
  task="请审查 ~/hermes-workspace/src/db.py 的代码质量，重点检查：1)安全性漏洞 2)错误处理 3)SQL注入风险。输出结构化审查报告。",
  model="claude-sonnet-4-20250514",
  tools=["read_file", "search_files", "terminal"],
  background=true
)

// 三个审查并行进行，主 Agent 继续处理其他任务
// 最终收到三份独立审查报告后汇总

8.2 多模型协同：mixture_of_agents※

mixture_of_agents（简称 MOA）是 Hermes 的多模型协同推理工具，属于 moa 工具集。它的核心思想是：针对真正困难的问题，不是用一个模型硬扛，而是让多个前沿 LLM 协同处理，最后由聚合器（aggregator）汇总输出。

MOA 最多发起 5 次 API 调用：4 个参考模型分别独立推理 + 1 个聚合器综合汇总。这种模式相当于找了 4 个不同背景的专家分别给你建议，最后一个主持人综合所有人的意见给出最终答案。

MOA vs. 普通单模型推理※

维度普通推理MOA 协同推理
模型调用1 次5 次（4 参考 + 1 聚合）
推理多样性单一视角多视角交叉验证
适用场景简单问答、日常任务复杂数学、高级算法、关键决策
Token 消耗低较高（按需使用）
所需环境标准 API Key需要 OPENROUTER_API_KEY

使用示例：复杂技术决策※

// 用 MOA 做技术选型决策
mixture_of_agents(
  task="我们需要为日活100万的SaaS应用选择数据库方案。请从以下维度评估 PostgreSQL vs MongoDB vs DynamoDB：1)扩展性 2)成本 3)开发效率 4)生态成熟度。给出明确的推荐方案和理由。",
  models=["gpt-4o", "claude-3-5-sonnet", "gemini-pro-1.5", "deepseek-v2"],
  aggregator="gpt-4o"
)

// 四个模型分别独立分析，然后聚合成最终建议
// 适合关键技术决策，避免单一模型的盲区

8.3 两种工具的选用指南※

delegate_task 和 mixture_of_agents 解决的是不同类型的问题：

  • 选 delegate_task——当你需要分工协作时：不同子任务需要不同工具（搜索、写代码、查文件），每个子 Agent 处理各自擅长的一部分，并行执行效率更高
  • 选 mixture_of_agents——当你需要多视角推理时：同一问题需要多个模型交叉验证，适合复杂数学、算法分析、关键决策等

8.4 实战示例：用 delegate_task 自动化测试流程※

让我们用一个完整场景来演示：主 Agent 收到「对这个 Python 项目做完整测试并生成报告」的任务。


graph TD
    A["用户：对这个项目做完整测试并出报告"] --> B["主 Agent：任务拆解"]
    B --> C["子Agent-1：单元测试"]
    B --> D["子Agent-2：集成测试"]
    B --> E["子Agent-3：性能测试"]
    C --> F["主 Agent：汇总三份测试结果"]
    D --> F
    E --> F
    F --> G["生成统一测试报告"]
    G --> H["✅ 返回给用户"]

主 Agent 收到任务后，通过 delegate_task 并行派发三个子 Agent：

// 子Agent-1：单元测试
delegate_task(
  task="对 ~/code/myproject 目录执行单元测试。步骤：1)安装依赖 pytest 2)运行 pytest --cov=src tests/ 3)生成覆盖率报告 4)输出测试结果摘要（通过/失败/错误数量）",
  tools=["terminal", "read_file"],
  background=true
)

// 子Agent-2：集成测试
delegate_task(
  task="对 ~/code/myproject 执行集成测试。步骤：1)启动测试数据库 2)运行 pytest tests/integration/ 3)检查API端点响应 4)输出测试结果和性能数据",
  tools=["terminal", "read_file"],
  background=true
)

// 子Agent-3：性能测试
delegate_task(
  task="对 ~/code/myproject 执行性能测试。步骤：1)使用 locust 做负载测试 2)模拟100并发用户 3)记录响应时间和吞吐量 4)输出性能报告",
  tools=["terminal", "read_file"],
  background=true
)

// 三个子Agent并行运行，主Agent等待所有结果后汇总

8.5 多智能体应用场景一览※

场景推荐工具效果
竞品调研（多源信息收集）delegate_task 并行搜索速度提升3倍，信息更全面
代码审查（多模块并行）delegate_task 并行审查不遗漏任何模块
技术选型决策mixture_of_agents多模型交叉验证，避免单一盲区
复杂数学证明mixture_of_agents多角度推理验证
自动化测试（单元+集成+性能）delegate_task 并行测试一次性完成全量测试
长篇报告生成（研究+写作分工）delegate_task 研究 + 写作专业分工，质量更高

💡 使用建议：mixture_of_agents Token 消耗较高，适合真正复杂的问题，日常简单任务用普通推理即可。delegate_task 则可以自由使用，特别适合需要不同工具或不同信息源的并行任务。

九、总结※

整个 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 能力，效率拉满 🚀

而当你开始处理更复杂的任务时，多智能体协作就是下一步进化的方向——让不同的 Agent 各司其职，并行工作，汇总输出，整体效率会再上一个台阶。

参考资料：Hermes Agent 中文社区 - Windows 安装文档｜Hermes 内置工具参考｜Hermes 工具运行时文档｜Hermes 持久记忆文档

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

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