Windows 环境部署 Hermes 全流程：从 WSL2 搭建到模型配置实操指南

本文基于 Windows 系统下安装 Hermes 的实战经验整理而成。整个部署流程的核心，在于打通 WSL2、Ubuntu 环境与 Hermes 配置的完整链路，而非单一命令操作。文中同步梳理了版本兼容、接口适配、参数填写等常见踩坑点，为 Windows 用户提供一份可直接参考的落地教程。

一、为何优先用 WSL2 安装 Hermes？

Hermes 的运行逻辑与依赖适配更贴合 Linux 环境。对 Windows 用户而言，无需重装系统、无需搭建双系统，通过 WSL2（Windows 子系统 Linux）构建虚拟 Linux 环境，是最便捷、稳定的部署方案。

整体部署路径：

1. 校验 Windows 系统版本，确认 WSL2 兼容性
2. 启用 WSL 与虚拟机平台核心功能
3. 安装 WSL2 专属 Linux 内核更新包
4. 部署并初始化 Ubuntu 子系统
5. 在 Ubuntu 中执行 Hermes 一键安装脚本
6. 对接大模型服务，完成 Hermes 自定义配置

下面按实操顺序，分步详解。

二、Windows 前置准备：启用 WSL2 核心能力

2.1 校验系统版本（必备前提）

WSL2 对 Windows 版本有明确要求，需满足Windows 10 1903（18362）及以上 / Windows 11 全版本。

• 快捷键Win+R，输入winver，回车查看系统版本号
• 版本过低时，先通过 Windows 更新完成系统升级，避免后续兼容报错

2.2 开启 WSL 与虚拟机平台功能

以管理员身份打开 PowerShell / 命令提示符，依次执行以下 2 条命令，启用核心系统功能：

powershell

# 启用Linux子系统功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台功能（WSL2依赖） dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

✅ 关键步骤：命令执行完成后，必须重启电脑，否则后续 WSL2 初始化、Ubuntu 转换会出现未知异常。

2.3 安装 WSL2 Linux 内核更新包

重启后，需安装微软官方 WSL2 内核包，确保虚拟 Linux 环境正常运行：

• 下载：WSL2 Linux 内核更新包（微软官方渠道）
• 安装：双击下载文件，按提示完成安装
• 再次重启电脑，让内核更新完全生效

2.4 设定 WSL2 为默认版本

重启后，在管理员 PowerShell 中执行命令，确保后续 Linux 分发版默认使用 WSL2：

powershell

wsl --set-default-version 2

三、Ubuntu 子系统部署与版本切换

3.1 安装 Ubuntu 子系统

1. 打开 Microsoft Store，搜索 “Ubuntu”，选择官方版本（推荐 22.04 LTS）安装
2. 安装完成后，在 Windows 开始菜单找到 Ubuntu，建议以管理员身份运行，减少权限报错

3.2 已有 Ubuntu 切换至 WSL2

若此前已安装 Ubuntu（默认 WSL1），需手动转换为 WSL2：

powershell

# 停止正在运行的Ubuntu wsl --terminate Ubuntu # 转换为WSL2版本 wsl --set-version Ubuntu 2 # 设为默认分发版（可选） wsl --set-default Ubuntu

3.3 WSL 异常修复

转换失败或运行报错时，执行以下命令排查修复：

powershell

# 更新WSL组件 wsl --update # 网络异常时，用国内源更新 wsl --update --web-download # 重置WSL后重试（谨慎操作，避免数据丢失） wsl --shutdown

四、Ubuntu 环境安装 Hermes

打开 Ubuntu 终端，进入 Linux 环境，执行 Hermes 官方一键安装脚本：

4.1 官方脚本（海外网络）

bash

运行

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

4.2 国内源脚本（网络不佳时）

bash

运行

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

4.3 安装过程说明

脚本会自动完成以下操作，全程无需手动干预：

1. 安装 uv 包管理器（Python 依赖管理工具）
2. 检测并安装 Python 3.11（Hermes 指定版本）
3. 下载 Hermes 核心程序与技能包
4. 配置环境变量，完成基础部署

等待终端提示安装完成，即可进入 Hermes 初始化配置界面。

五、Hermes 模型配置（自定义接口实操）

安装完成后，Hermes 会自动启动配置向导，核心是对接大模型服务，本文以自定义 OpenAI 兼容接口为例（适配国内主流平台）：

5.1 选择配置模式

向导提供 2 种模式，新手推荐快速配置（Quick setup），仅需配置模型供应商、接口与消息服务；进阶用户可选完整配置。

5.2 选择模型供应商

在供应商列表中，选择Custom endpoint（自定义接口），适配国内大模型平台（如 Routin、通义千问、DeepSeek 等）。

5.3 填写接口核心参数（关键！）

按平台文档，准确填写以下信息（参数错误会导致连接失败）：

1. API 基础地址（API base URL）：如https://cn.routin.ai/plan/v1
2. API 密钥（API key）：平台生成的专属密钥
3. 模型名称（Model name）：严格复制平台标准名称（如gpt-5.4）
4. 上下文长度、显示名称：按平台默认填写即可

5.4 消息服务配置（可选）

配置完成后，可选择连接消息平台（Telegram、飞书、微信等），实现跨设备控制；新手可先选择跳过（Skip），后续通过命令补充配置。

✅ 配置成功后，终端会显示 Hermes 欢迎界面，列出已加载的工具与技能包，至此部署完成。

六、安装后自检与常用维护命令

6.1 退出 Hermes

终端执行Ctrl+C，即可退出交互界面，返回 Ubuntu 命令行。

6.2 环境自检（必做）

检查配置完整性、依赖缺失、接口连通性：

bash

运行

hermes doctor

提示可自动修复时，执行：

bash

运行

hermes doctor --fix

6.3 重新配置

需修改模型接口、补充消息服务时，重启配置向导：

bash

运行

hermes setup

6.4 查看运行面板

监控 Hermes 运行日志、配置信息、技能状态：

bash

运行

hermes dashboard

6.5 版本更新

升级至最新版 Hermes，获取新技能与功能：

bash

运行

hermes update

七、总结：Windows 部署 Hermes 核心要点

1. WSL2 是基础：系统版本、虚拟机功能、内核更新包缺一不可，重启步骤不能省；
2. Ubuntu 必须 WSL2：旧版本及时转换，避免兼容问题；
3. 模型配置要精准：接口地址、密钥、模型名称严格按平台填写，切勿自定义命名；
4. 先自检再使用：部署后用hermes doctor排查问题，减少后续报错。

整体而言，Hermes 安装脚本成熟稳定，Windows 用户的核心难点集中在WSL2 环境搭建。只要打通 Windows 到 Linux 的过渡环节，后续安装、配置、维护都能高效完成，轻松拥有本地可执行的 AI 智能体。