🎯 教程目标

1. 解决 WSL 终端乱码、花屏问题

2. 成功部署 Hermes Agent 网页版管理面板

3. 实现后台运行，关闭终端不中断服务

4. 浏览器稳定访问，彻底告别终端操作

5. 最终效果：

📋 前置条件

• 已安装 WSL 2（Ubuntu 24.04 LTS）

• 已完成 Hermes Agent 基础安装（可执行 hermes --version 验证）

• 已配置好 Python 虚拟环境（~/.hermes/hermes-agent/venv）

🔧 第一阶段：安装网页版依赖（仅需执行一次）

步骤 1：进入 Hermes 虚拟环境

bash

运行

source ~/.hermes/hermes-agent/venv/bin/activate

终端前缀变为 (venv) 即成功

步骤 2：安装 Node.js + npm（网页构建必需）

bash

运行

# 更新软件源
sudo apt update
# 安装 Node.js 和 npm
sudo apt install -y nodejs npm
# 升级 npm 到稳定版
sudo npm install -g n
sudo n stable
# 刷新环境变量
PATH="$PATH"

步骤 3：安装 Hermes 网页界面依赖

bash

运行

# 安装网页版组件
pip install "hermes-agent[web]"

步骤 4：手动构建网页 UI（解决自动构建失败）

bash

运行

# 进入 web 目录
cd ~/.hermes/hermes-agent/web
# 安装前端依赖
npm install
# 构建网页界面
npm run build
# 回到用户主目录
cd ~

步骤 5：验证网页版启动

bash

运行

hermes dashboard

成功输出：Hermes Web UI → http://127.0.0.1:9119

后续 xdg-open 报错无需处理（WSL 无图形浏览器，服务已正常运行）

🌐 第二阶段：浏览器访问网页版

步骤 1：获取 WSL 真实 IP（解决 localhost 访问失败）

bash

运行

hostname -I

示例输出：172.21.78.204（每个人 IP 不同，以实际为准）

步骤 2：浏览器访问

打开 Windows 浏览器（Edge/Chrome），输入地址：

plaintext

http://<WSL_IP>:9119
# 示例：http://172.21.78.204:9119
# 也可直接尝试 http://localhost:9119（WSL 自动转发正常时可用）

成功进入 Hermes Agent 管理面板即完成部署

🚀 第三阶段：后台运行（关闭终端不中断）

方案一：零门槛 nohup 方案（推荐，无需快捷键）

步骤 1：停止当前前台运行的 dashboard

bash

运行

# 按 Ctrl+C 终止当前进程

步骤 2：一键后台启动

bash

运行

# 确保在 (venv) 虚拟环境中执行
nohup hermes dashboard > /dev/null 2>&1 &

执行后无输出即成功，直接关闭终端即可

步骤 3：验证后台运行

关闭终端后，浏览器重新访问 http://<WSL_IP>:9119，面板正常打开即成功

常用维护命令

bash

运行

# 查看后台进程
ps aux | grep hermes
# 停止后台运行
pkill -f "hermes dashboard"
# 重启后台（先停止再执行启动命令）
nohup hermes dashboard > /dev/null 2>&1 &

方案二：tmux 会话方案（适合需要查看日志的场景）

步骤 1：安装 tmux（仅需一次）

bash

运行

sudo apt update && sudo apt install -y tmux

步骤 2：创建后台会话

bash

运行

tmux new -s hermes-dashboard

步骤 3：进入虚拟环境并启动面板

bash

运行

source ~/.hermes/hermes-agent/venv/bin/activate
hermes dashboard

步骤 4：后台分离会话（关键！）

依次按下快捷键（不是输入字符）：

1. 按住 Ctrl 键，按一下 B，然后松开

2. 松开 Ctrl 键，按一下 D

终端显示 [detached (from session hermes-dashboard)] 即成功，可关闭终端

常用维护命令

bash

运行

# 重新连接会话（查看日志/停止服务）
tmux attach -t hermes-dashboard
# 停止服务（连接会话后按 Ctrl+C）
# 彻底删除会话
tmux kill-session -t hermes-dashboard

📌 第四阶段：日常使用流程（每次开机后）

1. 启动后台服务

bash

运行

# 打开 WSL 终端，执行
source ~/.hermes/hermes-agent/venv/bin/activate
nohup hermes dashboard > /dev/null 2>&1 &
# 直接关闭终端

2. 浏览器访问

plaintext

http://localhost:9119 或 http://<WSL_IP>:9119

❌ 常见问题排查

1. 浏览器 ERR_CONNECTION_REFUSED

• 检查 WSL 内服务是否运行：ps aux | grep hermes

• 重新启动服务：pkill -f "hermes dashboard" → 重新执行后台启动命令

• 用 WSL IP 替代 localhost 访问

2. 网页构建失败（npm install 报错）

• 切换 npm 国内源：npm config set registry https://registry.npmmirror.com

• 重新执行 npm install 和 npm run build

3. 虚拟环境失效

• 重新进入：source ~/.hermes/hermes-agent/venv/bin/activate

4. WSL 重启后服务中断

• 重新执行「日常使用流程」启动后台服务即可

✅ 最终效果

• 浏览器打开 http://localhost:9119，直接进入 Hermes Agent 网页管理面板

• 支持会话聊天、技能配置、日志查看等全功能

• 后台运行，关闭终端、WSL 窗口不影响服务

• 彻底解决终端乱码、花屏问题

💡 补充说明

• hermes gateway 是消息桥接服务（对接 Telegram/WhatsApp 等），不是网页聊天界面，请勿混淆

• 网页版默认端口 9119，如需修改可在 ~/.hermes/.env 中配置 DASHBOARD_PORT=xxxx

• WSL 完全关闭 / 电脑重启后，后台服务会终止，需重新启动