WSL2 + Ubuntu + Hermes Agent + Web UI 安装教程

手把手教你从零开始，在 Windows 上跑起 Hermes Agent。踩过的坑都写进去了，跟着走就行。

---

先说几句

这套教程是给想在 Windows 上用 Hermes 的朋友准备的。WSL2 是微软官方的 Linux 子系统，跑在 Windows 里但性能接近原生，比虚拟机省资源多了。

整个过程大概需要 30-60 分钟，主要看你网速。建议准备一个稳定的网络环境，因为要下载不少东西。

---

📋 目录

1. WSL2 安装
2. Ubuntu 初始化配置
3. Hermes Agent 安装
4. Web UI 安装部署
5. 常用命令速查

---

1. WSL2 安装

1.1 一键安装（推荐）

打开 PowerShell（用管理员身份），直接跑这条命令：

wsl --install -d Ubuntu-22.04

装完之后会让你重启电脑，重启就行。

注意： 如果你之前装过 WSL1 或者其他版本，可能会出问题。遇到报错就用下面的手动安装方法。

1.2 手动安装（一键安装失败时用）

分三步走，每一步都要等它跑完再进行下一步：

第一步：开启 WSL 功能

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

第二步：开启虚拟机平台

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

第三步：重启电脑

shutdown /r /t 0

重启完之后，继续：

第四步：设置 WSL2 为默认版本

wsl --set-default-version 2

第五步：安装 Ubuntu

去 Microsoft Store 搜索 “Ubuntu 22.04”，点击安装。或者用命令行：

wsl --install -d Ubuntu-22.04

1.3 验证安装

装完之后，检查一下是不是成功了：

wsl --status

应该会看到类似这样的输出：

默认版本: 2

再看看装了哪些发行版：

wsl --list --verbose

正常的话会显示：

  NAME            STATE           VERSION
* Ubuntu-22.04    Running         2

1.4 WSL 常见问题

WSL 启动不了

这种情况多半是没装好。试试重置：

wsl --shutdown
wsl --unregister Ubuntu-22.04
wsl --install -d Ubuntu-22.04

这会把原来的 Ubuntu 删掉重装，数据会丢，所以还没开始用的话就无所谓。

磁盘空间不够

WSL 的磁盘文件会越来越大，但不会自动收缩。清理一下：

# 先看看用了多少空间
wsl -d Ubuntu-22.04 -- df -h

# 清理系统垃圾
wsl -d Ubuntu-22.04 -- sudo apt autoremove -y
wsl -d Ubuntu-22.04 -- sudo apt autoclean

如果还是不够，需要压缩虚拟磁盘文件（这个操作比较复杂，一般用不到）。

localhost 访问不了 WSL 里的服务

这是 WSL2 的一个已知问题。有时候端口转发会失效。

解决方法一： 用 WSL 的 IP 地址访问

wsl hostname -I

会输出一个 IP 地址（比如 172.21.112.1），用这个 IP 替代 localhost。

解决方法二： 重启 WSL

wsl --shutdown
wsl

然后重新启动里面的服务。

---

2. Ubuntu 初始化配置

2.1 首次启动

从开始菜单找到 Ubuntu，点击打开。第一次会让你设置用户名和密码：

Enter new UNIX username: hermes
New password: ****
Retype new password: ****

密码输的时候屏幕不会显示任何东西，这是正常的，盲打就行。

2.2 更换软件源

Ubuntu 默认的软件源在国外，国内下载特别慢。换成阿里云的镜像：

# 先备份原来的配置，万一出问题可以恢复
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 写入新的源配置
sudo tee /etc/apt/sources.list <<'EOF'
deb http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy-security main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy-updates main restricted universe multiverse
deb http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
deb-src http://mirrors.aliyun.com/ubuntu/ jammy-backports main restricted universe multiverse
EOF

# 更新软件源列表
sudo apt update

如果你用的是 Ubuntu 24.04： 把上面的 jammy 全部替换成 noble。

2.3 安装基础工具

装一些后面会用到的工具：

# 更新系统
sudo apt update && sudo apt upgrade -y

# 装常用的命令行工具
sudo apt install -y curl wget git vim nano htop unzip jq build-essential

# 装 Python 开发相关的库
sudo apt install -y python3-pip python3-venv python3-dev \
    libssl-dev zlib1g-dev libffi-dev

说明：

• curl wget：下载文件用的
• git：代码版本管理
• vim nano：文本编辑器（选一个用就行）
• htop：查看系统资源占用
• build-essential：编译工具，装 Python 包有时候需要

2.4 安装 Node.js

Hermes Web UI 是用 Node.js 写的，所以需要装这个：

# 添加 NodeSource 的软件源
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 安装 Node.js
sudo apt install -y nodejs

# 设置 npm 使用国内镜像（加速下载）
npm config set registry https://registry.npmmirror.com

# 检查是否装成功
node --version
npm --version

如果 node --version 能输出版本号（比如 v20.x.x），就说明装好了。

2.5 配置 Git

Git 需要设置一下用户名和邮箱，不然以后提交代码会报错：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱@example.com"
git config --global init.defaultBranch main

2.6 配置 pip 国内源

Python 的包管理器 pip 默认也是用国外源，换成国内的：

mkdir -p ~/.pip
tee ~/.pip/pip.conf <<'EOF'
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
trusted-host = mirrors.aliyun.com
EOF

2.7 Ubuntu 配置常见问题

网络问题

如果你有代理（梯子），可以设置环境变量：

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

把 7890 改成你代理的端口。没有代理的话就用国内镜像，上面已经配置好了。

Node.js 安装失败

如果 npm install 报错，试试清除缓存：

npm cache clean --force

然后用淘宝镜像重新安装：

npm install -g hermes-web-ui --registry=https://registry.npmmirror.com

---

3. Hermes Agent 安装

3.1 一键安装

官方提供了一键安装脚本，直接跑：

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

装完之后需要重新加载 shell 配置：

source ~/.bashrc

注意： 这个脚本会自动创建虚拟环境、安装依赖，基本上不用手动操作。

3.2 验证安装

检查一下是否装成功：

hermes --version

如果输出版本号，就说明装好了。

再跑一下健康检查：

hermes doctor

这个命令会检查所有依赖是否齐全，如果有问题会提示你怎么修。

3.3 配置 API Key

Hermes 需要调用 AI 模型的 API，所以需要配置 API Key。

方法一：用配置向导（推荐新手）

hermes setup

它会一步步引导你选择模型、输入 API Key。

方法二：手动编辑配置文件

nano ~/.hermes/.env

在文件里添加你的 API Key（选一个就行）：

# Anthropic（推荐，Claude 模型）
ANTHROPIC_API_KEY=sk-ant-xxx

# OpenRouter（支持多种模型，一个 Key 用遍所有）
OPENROUTER_API_KEY=sk-or-xxx

# DashScope（阿里云，国内访问快）
DASHSCOPE_API_KEY=sk-xxx

# DeepSeek（国产模型，性价比高）
DEEPSEEK_API_KEY=sk-xxx

API Key 从哪来：

• Anthropic：https://console.anthropic.com/
• OpenRouter：https://openrouter.ai/
• DashScope：https://dashscope.console.aliyun.com/
• DeepSeek：https://platform.deepseek.com/

3.4 配置模型

选一个你想用的模型：

hermes model

会弹出一个交互式界面，让你选择模型和提供商。

或者直接指定：

hermes config set model.default anthropic/claude-sonnet-4

3.5 测试运行

跑一下试试：

hermes

会进入交互式聊天界面，输入问题测试一下。

或者单次查询：

hermes chat -q "你好，介绍一下你自己"

如果能正常回复，就说明一切正常。

3.6 Hermes 安装常见问题

安装失败

最常见的原因是 Python 版本太低：

python3 --version

需要 3.10 以上。如果版本不够，装一个新版本：

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.11

API Key 错误

检查一下配置文件：

cat ~/.hermes/.env

确保 Key 没有多余的空格、换行符。重新运行配置向导：

hermes setup

模型连不上

先检查网络：

curl -I https://api.anthropic.com

如果返回 200 或者 401，说明网络通。如果超时，可能是网络问题。

检查代理设置：

echo $HTTP_PROXY
echo $HTTPS_PROXY

如果没设置代理但需要代理，参考前面的网络配置部分。

---

4. Web UI 安装部署

4.1 Web UI 简介

hermes-web-ui 是 Hermes 的网页管理界面，可以在浏览器里管理配置、查看会话状态、管理 API Key。

技术栈是 Vue 3 + Vite，界面挺好看的。

默认跑在 8648 端口。

4.2 安装 hermes-web-ui

用 npm 全局安装：

npm install -g hermes-web-ui

装完之后验证一下：

hermes-web-ui version

输出版本号就说明装好了。

4.3 启动 Web UI

启动服务：

hermes-web-ui start

正常的话会看到：

✓ hermes-web-ui started
http://localhost:8648

然后在 Windows 浏览器里打开 http://localhost:8648 就能访问了。

4.4 自定义端口

如果 8648 端口被占用了，可以换一个端口：

hermes-web-ui start 3000

这样就会跑在 3000 端口。

4.5 管理服务

# 查看状态
hermes-web-ui status

# 停止服务
hermes-web-ui stop

# 重启服务
hermes-web-ui restart

# 重启并换端口
hermes-web-ui restart 3000

4.6 重置登录密码

默认登录是 admin / 123456。如果忘了密码：

hermes-web-ui reset-default-login

这会重置成默认密码。

如果 IP 被锁定了（输错太多次）：

hermes-web-ui clear-login-locks

4.7 更新 Web UI

有新版本的时候：

hermes-web-ui update

会自动更新到最新版并重启。

4.8 Web UI 目录结构

安装后会在用户目录下创建配置文件夹：

~/.hermes-web-ui/
├── server.pid      # 进程 ID
├── server.log      # 日志文件
└── .token          # 登录 token

4.9 访问 Web UI

本地访问：
直接打开 http://localhost:8648

局域网访问：
先获取 WSL 的 IP：

hostname -I

然后用 http://<IP地址>:8648 访问。

Windows 访问 WSL 服务：
一般情况下，直接用 http://localhost:8648 就行。如果不行，就用上面的 IP 方法。

4.10 Web UI 常见问题

安装失败

检查 Node.js 版本：

node --version

需要 18 以上。如果版本不够，重新安装 Node.js。

清除缓存重试：

npm cache clean --force
npm install -g hermes-web-ui

端口被占用

查看谁在用这个端口：

sudo lsof -i :8648

找到进程 ID（PID），然后杀掉：

sudo kill <PID>

或者换个端口启动：

hermes-web-ui start 3000

访问不了

先检查服务状态：

hermes-web-ui status

如果服务没跑起来，看看日志：

tail -f ~/.hermes-web-ui/server.log

重启试试：

hermes-web-ui restart

如果还是不行，检查防火墙：

sudo ufw status
sudo ufw allow 8648/tcp

忘记密码

重置就行：

hermes-web-ui reset-default-login

会恢复成默认的 admin / 123456。

---

5. 常用命令速查

WSL 命令（在 PowerShell 里执行）

# 查看状态
wsl --status

# 列出所有发行版
wsl --list --verbose

# 启动 Ubuntu
wsl

# 关闭所有 WSL
wsl --shutdown

# 终止某个发行版
wsl --terminate Ubuntu-22.04

# 删除某个发行版（数据会丢！）
wsl --unregister Ubuntu-22.04

# 设置默认发行版
wsl --set-default Ubuntu-22.04

# 备份（导出）
wsl --export Ubuntu-22.04 D:\backup\ubuntu.tar

# 恢复（导入）
wsl --import Ubuntu-New D:\wsl-new D:\backup\ubuntu.tar

Hermes 命令（在 WSL 里执行）

# 启动聊天
hermes

# 单次查询
hermes chat -q "你的问题"

# 配置向导
hermes setup

# 编辑配置文件
hermes config edit

# 健康检查
hermes doctor

# 查看版本
hermes --version

# Gateway 管理
hermes gateway run           # 前台运行
hermes gateway install       # 安装为系统服务
hermes gateway start         # 启动服务
hermes gateway stop          # 停止服务
hermes gateway restart       # 重启服务
hermes gateway status        # 查看状态

# 技能管理
hermes skills list           # 列出已安装的技能
hermes skills install ID     # 安装技能

# 会话管理
hermes sessions list         # 列出会话
hermes --continue            # 恢复上次会话

Web UI 命令

# 服务管理
hermes-web-ui start          # 启动
hermes-web-ui stop           # 停止
hermes-web-ui restart        # 重启
hermes-web-ui status         # 查看状态

# 指定端口
hermes-web-ui start 3000
hermes-web-ui restart 3000

# 登录管理
hermes-web-ui reset-default-login  # 重置密码
hermes-web-ui clear-login-locks    # 解除锁定

# 更新
hermes-web-ui update

文件互访

# 在 WSL 里访问 Windows 文件
ls /mnt/c/Users/
ls /mnt/d/

# 在 Windows 里访问 WSL 文件
# 打开资源管理器，地址栏输入：
\\wsl$\Ubuntu-22.04\home\hermes

# 在 WSL 里打开 Windows 资源管理器
explorer.exe .

---

快速开始（4 步）

如果你想快速跑起来，按这个顺序来：

第 1 步：装 WSL

PowerShell 管理员身份运行：

wsl --install -d Ubuntu-22.04

重启电脑。

第 2 步：配置 Ubuntu

打开 Ubuntu，执行：

sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git python3-pip nodejs npm

第 3 步：装 Hermes

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

按提示配置 API Key。

第 4 步：装 Web UI

npm install -g hermes-web-ui
hermes-web-ui start

浏览器打开 http://localhost:8648，用 admin / 123456 登录。

---

最后说几句

整个过程其实不难，就是步骤比较多。遇到问题别慌，看看错误信息，大部分都能在网上找到解决方案。

Hermes 的官方文档：https://hermes-agent.nousresearch.com/docs/

GitHub 仓库：https://github.com/NousResearch/hermes-agent

有问题可以去 GitHub 提 Issue，社区响应还挺快的。

---

适用系统： Windows 10/11 + WSL2 + Ubuntu 22.04/24.04