Windows 安装部署 Hermes Agent 喂饭级教程

前言

Hermes Agent 作为当前最火的自进化 AI 智能体，凭借自动学习技能、持久记忆、越用越聪明的特性火爆整个开源社区。

虽然 Hermes Agent 官方原生支持 Linux 和 macOS，但通过 Windows Subsystem for Linux (WSL2)，我们完全可以在 Windows 上获得丝滑、原生般的体验！ Windows 用户安装：Hermes 不支持原生 Windows，必须通过 WSL2 运行。

为什么必须用 WSL2？

根据官方文档和社区实践，Hermes Agent 是一个基于 Python 的复杂系统，重度依赖 Linux 环境下的工具链（如 uv、特定的系统库、systemd 进程管理等）。直接在 Windows 原生命令行（CMD/PowerShell）或 Git Bash 中安装几乎肯定会失败。

WSL2 在 Windows 内核上运行一个完整的 Linux 内核，为你提供了一个与 Ubuntu 等发行版几乎无异的开发环境，是目前在 Windows 上运行 Hermes Agent 唯一可靠且官方推荐的方式。

本文将带你 开启 WSL2 → 安装 Ubuntu → 一键部署 Hermes → 配置大模型，全程避坑、亲测可跑通使用。

一、重要说明（必看）

Hermes Agent 官方不支持原生 Windows，仅支持 Linux/macOS
Windows 唯一稳定安装方案：WSL2 + Ubuntu 22.04
一键脚本自动安装：Python/Node.js/uv/依赖全搞定
支持飞书、微信、QQ、钉钉、Telegram 等多平台接入
支持国内模型：DeepSeek、MiniMax、Kimi、通义千问、智谱 GLM

二、环境准备

Windows 10 1903 以上 / Windows 11
已开启虚拟化（BIOS 开启或笔记本默认开启）
管理员权限
有网络

三、第一步：安装并配置 WSL2

1. 启用 WSL 与虚拟机平台

以管理员身份打开 PowerShell，执行：

# 启用 "适用于 Linux 的 Windows 子系统" 可选功能
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux/all /norestart
# 启用 "虚拟机平台" 可选功能
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform/all /norestart

✅ 执行完必须重启电脑 这一步很关键，不重启的话，后面的 WSL 2 设置或 Ubuntu 转换可能会出现各种奇怪问题。

2. 设置 WSL2 为默认版本

重启后打开 PowerShell：

# 将 WSL2 设置为默认版本
wsl --set-default-version 2

这条命令的作用是：让后续新安装的 Linux 分发版默认使用 WSL 2。

3. 安装 Ubuntu

可以直接在微软商店搜索：Ubuntu 22.04 LTS 安装，也可以使用命令来安装

微应用商店安装

打开 Microsoft Store (微软应用商店)。
搜索 "Ubuntu"。
选择 "Ubuntu 22.04 LTS" (或最新 LTS 版本)，点击 "获取" 进行安装。
初始化 Ubuntu

安装完成后，在开始菜单中启动 "Ubuntu"。

首次启动会要求你创建一个 Linux 用户名和密码（这与你的 Windows 账户无关，请牢记）。初始化完成后，你就拥有了一个功能完备的 Linux 终端！

💡 避坑提示：如果国内网络不好，可能会遇到网络问题导致安装缓慢或失败。可以使用下面的命令行来安装，尝试在 PowerShell 中使用： wsl --install -d Ubuntu-22.04 --web-download 并配合系统代理（如果有的话）。此外，安装后建议立即更换国内源（如清华源）以加速后续操作。

命令行安装

以管理员身份打开 PowerShell，执行：

# 安装最新版本
wsl --install
#指定版本安装
wsl --install -d Ubuntu-22.04--web-download

执行完后，通常需要重启电脑。

重启后再打开终端，第一次进入 WSL 时，系统会让你完成 Ubuntu 用户名和密码初始化。这个密码是你在 Linux 环境里的本地密码（务必记住），后面执行 sudo 时会用到。

✅ 为什么选 22.04 LTS？该版本是 Hermes Agent 官方测试矩阵中的标准环境，兼容性最佳，社区问题最少。

4. 验证 WSL2 版本

wsl -l -v

看到 VERSION 为 2 即成功。

3. 启动 Ubuntu

在 Windows 左下角开始菜单中找到 Ubuntu。为了减少权限相关的问题，我这里选择以管理员身份运行。

进入 Ubuntu 后，就可以开始安装 Hermes 了。

四、Ubuntu 内一键安装 Hermes

打开 Ubuntu 终端，执行：

1. 更新系统（可选但是推荐执行）

sudo apt update && sudo apt upgrade -y

这一步主要是避免系统包太旧，后面装东西时出一些奇奇怪怪的问题。这能确保你拥有最新的安全补丁和库文件，避免潜在的依赖冲突。

2. 官方一键安装（核心命令）

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Install ripgrep for faster file search ffmpeg for TTS voice messages?[Y/n] y
这里会有个提示安装可选的工具ripgrep和ffmpeng，输入y,这里我一并安装了：安装ripgrep以加快文件搜索速度，安装ffmpeg以处理TTS语音消息
脚本跑完之后，会进入配置阶段，配置大模型，QQ/微信等，这里可以直接配置，也可以选择自定义先跳过。
最后提示要不要启动
Launch hermes chat now?[Y/n]: n 这里我没有直接启动
提示加载环境变量
Reload your shell to use 'hermes' command:
source ~/.bashrc

如果网络不佳，脚本安装不顺利，可以执行这个，使用国内源安装：

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

这个命令做的事情比较多。

安装 uv（超快的 Python 包安装器和虚拟环境管理器）安装 Python 3.11+ 克隆 Hermes Agent 仓库到 ~/hermes-agent 创建并激活虚拟环境安装所有依赖（包括 ripgrep, ffmpeng, fd-find 等高效工具）将 hermes 命令添加到你的 PATH

3. 重载环境变量

source ~/.bashrc

4. 验证安装

hermes --version

Hermes Agent v0.13.0 (2026.5.7)

出现版本号即安装成功！

五、配置大模型提供商 API（关键）

执行配置命令向导：

hermes setup

在交互式界面中：

选择你的模型提供商（如 OpenAI, Anthropic, OpenRouter, 或国内的大模型如 MiniMax、阿里云百炼、智谱 GLM）。
输入对应的 API Key。
选择一个默认模型(这里我使用的是国内的MiniMax，价格比较便宜，速度也快)

支持主流厂商（选一个即可）

OpenRouter
DeepSeek
MiniMax
Kimi / Moonshot
智谱 ZAi / GLM
通义千问
OpenAI

配置内容：

API Key
模型名称（如 MiniMax-M2.7）
BASE_URL

六、接入飞书机器人（可选）

后续文章详细讲解，敬请持续关注，先大概介绍下飞书接入。

1. 飞书开放平台创建应用

开启机器人权限：

im:message:sendasbot
im:message:read
contact:user:readonly

2. 获取 AppID + AppSecret

3. 执行网关配置

hermes gateway setup

选择：feishu输入 AppID、AppSecret 连接模式选：websocket（无需公网IP）

4. 审批配对用户

hermes pairing approve feishu 你的飞书ID

七、启动与使用Hermes

1. 启动 Hermes 对话

hermes

输入想要问的问题直接可以对话了

2. 启动网关（飞书/QQ/微信）

hermes gateway run

3. 打开 Web 控制面板

hermes dashboard

访问：http://127.0.0.1:9119

八、Windows 部署可能遇到的 9 个坑

❌ 不能在 PowerShell 直接装，必须进 Ubuntu
❌ 不能用 root 安装，必须普通用户
❌ 网络失败：换国内源或加速
❌ 命令不存在：执行 source~/.bashrc
❌ 飞书收不到消息：检查长连接、权限、审批
❌ 模型调用失败：检查 API Key、模型名称、Endpoint
❌ WSL 安装失败：开启虚拟化、更新 Windows
❌ 安装卡住：Ctrl+C 重试，换国内安装脚本
❌ 卸载不干净：使用 hermes uninstall

九、从 OpenClaw 一键迁移

hermes claw migrate

自动迁移：配置、记忆、技能

十、一键卸载 Hermes

hermes uninstall

选择 2 完全卸载

十一、总结

Windows 部署 Hermes Agent 唯一正确路线：

WSL2 → Ubuntu 22.04 → 一键脚本 → 模型配置 → 网关接入

就能拥有一个会自我进化、7×24 小时在线的 AI 智能体，可写代码、读文档、做自动化、接 IM 机器人。

参考链接：https://cloud.tencent.com/developer/article/2655093 https://blog.csdn.net/weixin_41903114/article/details/160346490 https://blog.csdn.net/landonzeng/article/details/160230691